Creating payments

Forte's Payments API lets you charge your end-users with one-off Payments or recurring Subscriptions. Forte provides payment tracking, tax calculation, and simplified webhooks for you, and manages chargebacks automatically.

Your company is always the merchant of record for Payments on Forte. Fees are calculated on a per-customer basis depending on account size and industry, and range from 0% (no markup over Stripe) to 3% (high risk industries and small accounts).

Prerequisites

• Your Forte Project owner has completed compliance registration.
• Your project is in sandbox mode (charges run against Stripe Test mode) or live (real money). Sandbox routing is automatic — there is no separate flag on the Payment.

Payments and payment previews

Forte provides one endpoint for cart previews and a separate endpoint for checkout flows. Preview is read-only. Call it as the user changes items, quantities, addresses, or coupons. Create is the write step. Call it once when the user selects Checkout.

Each endpoint has two API surfaces. Use client-side routes when a signed-in user pays for themselves. Use server-side routes when your backend creates a payment for a user it authenticated another way. See API Surfaces for details.

Client-side (signed-in user session):

• POST /api/v1/{projectId}/users/me/payments/preview
• POST /api/v1/{projectId}/users/me/payments

Server-side (API key):

• POST /api/v1/projects/{projectId}/users/{userId}/payments/preview
• POST /api/v1/projects/{projectId}/users/{userId}/payments

Previewing a payment total with tax

import { ForteClient } from "@forteplatforms/sdk";
 
const forte = new ForteClient();
 
const preview = await forte.users.createPaymentPreview({
  projectId,
  createPaymentPreviewRequest: {
    currency: "usd",
    lineItems: [
      { description: "Pro plan", unitAmountCents: 2500, quantity: 1, taxCode: "txcd_10000000" },
    ],
    customerAddress: {
      line1: "354 Oyster Point Blvd",
      city: "South San Francisco",
      state: "CA",
      postalCode: "94080",
      country: "US",
    },
  },
});
 
const { subtotalCents, taxCents, amountCents } = preview;

The response includes subtotalCents, taxCents, amountCents, currency, and per-line taxAmountCents. If you omit customerAddress, no tax is computed and amountCents == subtotalCents.

taxCode is Stripe's product tax category — for example, txcd_99999999 (general goods) or txcd_10000000 (digital goods). Tax is always applied as EXCLUSIVE (added on top of the unit price).

Use txcd_92010001 for shipping charges. Forte finds every line with this code, sums them, and reports the total as shipping cost so tax calculates correctly — some regions tax shipping differently from goods.

Creating a payment (and Stripe PaymentIntent)

When the user clicks "Pay," call createPayment with the same payload, optionally adding a description and metadata. Payments are scoped to a specific user, so the userId in the URL must match the user you charge.

const result = await forte.users.createPayment({
  projectId,
  createPaymentRequest: {
    currency: "usd",
    description: "May 2026 invoice",
    lineItems: [
      { description: "Pro plan", unitAmountCents: 2500, quantity: 1, taxCode: "txcd_10000000" },
    ],
    customerAddress: { line1: "...", city: "...", state: "...", postalCode: "...", country: "US" },
  },
});
 
const { payment, stripeClientSecret, stripePublishableKey, stripeConnectedAccountId } = result;

Response:

{
  "payment": {
    "id": "pay_...",
    "state": "DRAFT",
    "subtotalCents": 2500,
    "taxCents": 219,
    "amountCents": 2719,
    "stripePaymentIntentId": "pi_...",
    "stripeTaxCalculationId": "taxcalc_..."
  },
  "stripeClientSecret": "pi_..._secret_...",
  "stripePublishableKey": "pk_...",
  "stripeConnectedAccountId": "acct_..."
}

Choosing which payment methods to accept

By default a Payment accepts credit and debit cards only. To offer more, pass supportedPaymentMethods on createPayment — the list of methods the customer may use when confirming:

const result = await forte.projects.createPayment({
  projectId,
  userId,
  createPaymentRequest: {
    currency: "usd",
    lineItems: [{ description: "Pro plan", unitAmountCents: 2500, quantity: 1 }],
    // Offer both a card and a US bank account on this payment:
    supportedPaymentMethods: ["CREDIT_CARD", "ACH_DIRECT_DEBIT"],
  },
});

Omit the field (or pass an empty list) to keep the card-only default. The Payment Element you mount with the returned stripeClientSecret shows exactly the methods you allowed. When you pin a specific saved method with paymentMethodId, supportedPaymentMethods is ignored — the method (and its type) is already chosen.

Confirming the payment in the browser with Stripe Elements

The three Stripe identifiers in the response (stripeClientSecret, stripePublishableKey, stripeConnectedAccountId) are everything Stripe.js needs to mount a Payment Element bound to your connected account. Pass them through to your frontend as-is.

import { loadStripe } from "@stripe/stripe-js"
 
const stripe = await loadStripe(stripePublishableKey, { stripeAccount: stripeConnectedAccountId })
const elements = stripe.elements({ clientSecret: stripeClientSecret })
const paymentElement = elements.create("payment")
paymentElement.mount("#payment-element")
 
// On submit:
await stripe.confirmPayment({ elements, confirmParams: { return_url: "..." } })

Charging a saved method off-session (server-initiated)

The preceding flow is on-session — the customer is present and confirms in the browser. To charge a method already on file without the customer present (a server-initiated, one-off charge), pass offSession: true with the saved paymentMethodId. No client secret exists to confirm; Forte charges immediately.

const result = await forte.projects.createPayment({
  projectId,
  userId,
  createPaymentRequest: {
    currency: "usd",
    lineItems: [{ description: "Usage — May", unitAmountCents: 4200, quantity: 1 }],
    paymentMethodId: "pm_...", // a card or bank account the user previously saved
    offSession: true,
  },
});

• Cards complete (or decline) synchronously. A decline returns PAYMENT_DECLINED.
• ACH bank accounts can't fail synchronously — the Payment comes back PROCESSING and settles to COMPLETED or FAILED over the following business days. Listen for the PAYMENT_COMPLETED / PAYMENT_FAILED triggers to learn the outcome.

offSession: true requires paymentMethodId — without it the call returns PAYMENT_OFF_SESSION_METHOD_REQUIRED. To put a card or bank account on file for later, see saving a payment method.

Payment lifecycle and state mapping

The state on a Forte Payment reflects the underlying Stripe PaymentIntent's status:

Forte updates this automatically through Stripe webhooks. When a Payment hits COMPLETED and had a stripeTaxCalculationId, Forte also finalizes a Stripe Tax Transaction so your tax bookkeeping stays correct.

Refunding a payment

refundPayment issues a full refund of a COMPLETED payment and transitions it to REFUNDED. Forte returns the entire charged amount, including any tax, to your end-customer.

Only COMPLETED payments can be refunded. Refunding a payment in any other state returns PAYMENT_NOT_REFUNDABLE, and refunding one that is already refunded returns PAYMENT_ALREADY_REFUNDED. The call returns the updated Payment with state: "REFUNDED".

import { ForteClient } from "@forteplatforms/sdk";
 
const forte = new ForteClient({ apiKey: process.env.FORTE_API_KEY });
 
const payment = await forte.projects.refundPayment({
  projectId,
  userId,
  paymentId,
});
 
// payment.state === "REFUNDED"

You can also refund a payment from the Forte console: open the user's page, find the payment in the Payments section, and use the Refund action on any completed payment.

Payment triggers (webhooks to your services)

When a Payment changes state, Forte invokes a Payment Trigger (in practice, an HTTP POST call) to one of your Forte Services. Use this to kick off fulfillment work as a side effect of a payment — for example, issue licenses, email receipts, write to your own ledger, or notify downstream systems.

Forte delivers triggers over a private network to your Service.

Trigger events

Creating a payment trigger

Triggers are project-scoped. Create, update, and delete them from the Forte Project's settings page in the web console.

Receiving and processing trigger events

For each matching event, Forte sends a POST request to your target Service and URL path with the following headers and body:

Headers:

Body:

{
  "userId": "usr_...",
  "paymentId": "pay_...",
  "paymentTime": "2026-05-10T18:42:11.123Z",
  "state": "COMPLETED"
}

• userId — the Forte User the payment belongs to.
• paymentId — the Forte Payment ID. GET it via the payments API if you need the full object.
• paymentTime — ISO-8601 UTC timestamp of the state transition.
• state — uppercase, one of "COMPLETED", "FAILED", or "REFUNDED".

Trigger retry policy

You can view any failed (non-HTTP 2xx) trigger invocations in the web console. Forte retries them as follows:

Forte abandons the trigger after 5 failed attempts. Contact Forte support if you need help replaying dropped events or accessing old data for abandoned triggers.

Best practices for trigger handlers

• Return 2xx in under 30 seconds.
• Make handling idempotent on (paymentId, state) so that retries are safe.

Testing trigger handlers locally

While you're building a handler, you can fire any of your project's triggers directly at your local dev server using the Forte CLI — same JSON body and X-Forte-Trusted: 1 header that production sends, no real payment state change required.

forte payment-triggers test

The command walks you through picking a trigger, searching for a user, and choosing one of that user's recent payments. Once you're on the "Ready to fire" screen:

Skip the picker by passing the trigger ID directly:

forte payment-triggers test pmt_trigger_<id>

Sandbox mode vs. live payments

If your project has sandbox mode enabled, every Payment runs against your sandbox Stripe Connect account in Stripe Test mode — the publishable key returned is a pk_test_.... Switch the project to live (or use a separate live project) to charge real cards.

Audit trail and logging

Forte writes payments and state events to the audit trail for the user they belong to. Payment previews are not logged.