Developer platform

One-time payments

Create hosted checkout sessions for one-time ForgeCredit payments.

ForgePay is not a bank. ForgeCredit is an internal settlement unit for services available in the ForgePay ecosystem.

Create a checkout session

A checkout session contains the FGC amount, description, redirect URLs and optional merchant metadata. ForgePay returns a hosted `checkout_url`.

curlbash

curl -X POST http://localhost:3000/api/v1/checkout/sessions \
  -H "Authorization: Bearer fp_test_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_1001" \
  -d '{
    "amount_fgc": "250.00",
    "currency": "FGC",
    "description": "AI writing package",
    "success_url": "https://merchant.example/success",
    "cancel_url": "https://merchant.example/cancel",
    "customer_reference": "customer_42",
    "metadata": {
      "order_id": "1001"
    }
  }'

JavaScriptjavascript

const response = await fetch("http://localhost:3000/api/v1/checkout/sessions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fp_test_xxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
    "Idempotency-Key": "order_1001"
  },
  body: JSON.stringify({
    amount_fgc: "250.00",
    currency: "FGC",
    description: "AI writing package",
    success_url: "https://merchant.example/success",
    cancel_url: "https://merchant.example/cancel",
    customer_reference: "customer_42",
    metadata: { order_id: "1001" }
  })
});

const checkoutSession = await response.json();
console.log(checkoutSession.checkout_url);

Example response

Redirect the customer to `checkout_url`. The hosted page shows the merchant name, amount and ForgePay authorization controls.

JSONjson

{
  "id": "checkout_cuid_example",
  "object": "checkout_session",
  "mode": "test",
  "status": "created",
  "currency": "FGC",
  "amount_minor": "25000",
  "amount_fgc": "250",
  "eur_cents": "250",
  "checkout_session_id": "checkout_cuid_example",
  "checkout_url": "http://localhost:3000/checkout/checkout_cuid_example",
  "customer_email": null,
  "customer_reference": "customer_42",
  "description": "AI writing package",
  "success_url": "https://merchant.example/success",
  "cancel_url": "https://merchant.example/cancel",
  "external_reference": null,
  "expires_at": "2026-06-03T12:30:00.000Z",
  "created_at": "2026-06-03T12:00:00.000Z",
  "updated_at": "2026-06-03T12:00:00.000Z"
}

Payment confirmation

The merchant never receives the user's transaction PIN. In test mode, confirmation creates a test transaction, marks the checkout as paid and sends a webhook without debiting live ForgeCredit balances or creating live settlement. When live mode is enabled later, the equivalent live flow will debit allowed wallet funds and credit merchant settlement.