PayForgeDOCS
Dashboard
API

API Reference

Complete reference for the PayForge REST API. All endpoints require authentication via Bearer token.

Base URL:https://api.payforge.dev/api/v1
API PlaygroundTransactionsMerchantsFraud IntelligenceWebhooksAPI Keys

API Playground

Make real API calls against the live backend directly from the docs. Click Quick Login to authenticate with the demo account, then send requests to see actual responses.

API Playground
Not authenticated
GET/api/v1/transactions

Fetch your recent transactions. Try it now!

API Playground
Not authenticated
POST/api/v1/transactions

Create a new payment transaction.

API Playground
Not authenticated
GET/api/v1/merchants/me/analytics

Get your merchant analytics including volume, revenue, and fraud rate.

API Playground
Not authenticated
GET/api/v1/fraud/stats

Get aggregate fraud statistics.

Transactions

Create, capture, refund, and void payments. All POST endpoints support idempotency via the X-Idempotency-Key header.

POST/api/v1/transactions

Create a new transaction. The payment will be authorized, fraud-scored, and captured automatically by the Saga orchestrator.

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

List transactions with filtering and pagination.

Parameters

pageinteger

Page number

per_pageinteger

Results per page (max 100)

statusstring

Filter: captured, authorized, refunded, voided, blocked, failed, settled

fromstring

Start date (ISO 8601)

tostring

End date (ISO 8601)

min_amountinteger

Minimum amount in cents

max_amountinteger

Maximum amount in cents

curl -X GET "https://api.payforge.dev/api/v1/transactions" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"
GET/api/v1/transactions/:id

Get full details of a specific transaction.

curl -X GET "https://api.payforge.dev/api/v1/transactions/:id" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"
POST/api/v1/transactions/:id/capture

Capture an authorized payment. Optionally specify a partial capture amount.

curl -X POST "https://api.payforge.dev/api/v1/transactions/:id/capture" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 5000 }'
POST/api/v1/transactions/:id/refund

Refund a captured payment. Supports full and partial refunds.

curl -X POST "https://api.payforge.dev/api/v1/transactions/:id/refund" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 2500 }'
POST/api/v1/transactions/:id/void

Void an authorized payment before capture.

curl -X POST "https://api.payforge.dev/api/v1/transactions/:id/void" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"
GET/api/v1/transactions/:id/events

Get the immutable event stream for a transaction. Shows every state change with timestamps.

curl -X GET "https://api.payforge.dev/api/v1/transactions/:id/events" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"
GET/api/v1/transactions/:id/ledger

Get double-entry ledger entries for a transaction.

curl -X GET "https://api.payforge.dev/api/v1/transactions/:id/ledger" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"

Merchants

Manage your merchant profile, view analytics, and check balances.

GET/api/v1/merchants/me

Get your merchant profile and configuration.

curl -X GET "https://api.payforge.dev/api/v1/merchants/me" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"
GET/api/v1/merchants/me/analytics

Get aggregate analytics for your merchant.

curl -X GET "https://api.payforge.dev/api/v1/merchants/me/analytics" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"
GET/api/v1/merchants/me/balance

Get current account balances by type.

curl -X GET "https://api.payforge.dev/api/v1/merchants/me/balance" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"
PATCH/api/v1/merchants/me

Update your merchant settings.

curl -X PATCH "https://api.payforge.dev/api/v1/merchants/me" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Updated Merchant Name",
  "webhook_url": "https://example.com/webhooks"
}'

Fraud Intelligence

Review fraud cases, view ML-powered risk scores with SHAP explanations, and manage decisions.

GET/api/v1/fraud/cases

List fraud cases for your merchant with filtering by status and priority.

Parameters

statusstring

Filter: open, confirmed_fraud, false_positive

prioritystring

Filter: low, medium, high, critical

pageinteger

Page number

curl -X GET "https://api.payforge.dev/api/v1/fraud/cases" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"
POST/api/v1/fraud/cases/:id/review

Submit a review decision for a fraud case.

curl -X POST "https://api.payforge.dev/api/v1/fraud/cases/:id/review" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "false_positive",
  "notes": "Verified with customer via phone"
}'
GET/api/v1/fraud/stats

Get aggregate fraud statistics for your merchant.

curl -X GET "https://api.payforge.dev/api/v1/fraud/stats" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"

Webhooks

View webhook delivery history and test your endpoint.

GET/api/v1/webhooks/deliveries

List recent webhook delivery attempts.

curl -X GET "https://api.payforge.dev/api/v1/webhooks/deliveries" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"
GET/api/v1/webhooks/status

Get webhook endpoint status and delivery success rate.

curl -X GET "https://api.payforge.dev/api/v1/webhooks/status" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"
POST/api/v1/webhooks/test

Send a test webhook event to your configured endpoint.

curl -X POST "https://api.payforge.dev/api/v1/webhooks/test" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "event_type": "payment.captured" }'

API Keys

Manage API keys for programmatic authentication.

GET/api/v1/api_keys

List all API keys for your merchant.

curl -X GET "https://api.payforge.dev/api/v1/api_keys" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"
POST/api/v1/api_keys

Create a new API key. The full key value is only returned once at creation.

curl -X POST "https://api.payforge.dev/api/v1/api_keys" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production Key" }'
POST/api/v1/api_keys/:id/rotate

Rotate an API key. Generates a new key and revokes the old one.

curl -X POST "https://api.payforge.dev/api/v1/api_keys/:id/rotate" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json"