Forter Managed

Forter's Orchestration service provides one unified integration that unlocks multiple services - Fraud Prevention, Predictive Payment Routing (PPR), and Payment Orchestration. Each service can be enabled independently or combined, with no additional engineering work, allowing merchants to start with any capability and expand seamlessly over time.

End-to-End Flow

flowchart TD
    A["Customer enters card details"] --> B["Hosted Fields tokenizes card"]
    B --> C["Create Payment via API"]
    C --> D{"Fraud Check"}
    D -- Decline --> E["Transaction Rejected"]
    D -- Approve --> F{"3DS Required?"}
    F -- Yes --> G["Execute 3DS Challenge"]
    G --> H{"Challenge Success?"}
    H -- No --> E
    H -- Yes --> I["Route to Optimal PSP"]
    F -- No --> I
    I --> J{"Authorization Success?"}
    J -- No --> K["PPR Retry with Next PSP"]
    K --> J
    J -- Yes --> L["Payment Captured"]
    L --> M["Webhook Notification"]

Integration Steps

Add Hosted Fields SDK

Add Forter's checkoutTools library to your checkout page, wherever the card entry iframe is located. The script should be pasted directly before the closing HTML </body> tag.

<script
  type="text/javascript"
  data-site-id="YOUR_SITE_ID"
  id="checkoutTools__script"
  src="https://sdk.checkouttools.com/v1.2/full.js">
</script>

Generate an Auth Token

Before using the Forter Hosted Fields SDK, your backend must generate a temporary authentication token.

Make a request from your backend to /v1/tokenization/client-key endpoint in the Tokenization API, including the required authentication headers.

Example Request

{
  "ttlMinutes": 60
}

Example Response

{
  "clientKey": "TOKEN_VALUE"
}

Tokenize Card Data Using Hosted Fields SDK

Initialize the SDK

Call the init method on the hosted fields SDK, passing in the auth token you received in the previous step:

const forterCollect = await window.checkoutTools.collect.init({
  environment: 'sandbox',
  authToken: 'TOKEN.VALUE'
});

Add Hosted Fields placeholders to the checkout page form

<form>
  <div id="cc-holder"></div>
  <div id="cc-number"></div>
  <div id="cc-exp"></div>
  <div id="cc-cvc"></div>
</form>

Initialize the Hosted Fields using the SDK instance

forterCollect.addFields({
  'cc-holder': {
    type: 'CARD_HOLDER_NAME'
  },
  'cc-number': {
    type: 'CARD_NUMBER',
  },
  'cc-exp': {
    type: 'CARD_EXPIRATION_DATE',
  },
  'cc-cvc': {
    type: 'CARD_CVC',
  }
});

Submit the form & receive a token

When the customer submits the form, call the submit() method to receive a single-use token:

const tokenResult = await forterCollect.submit();
console.log(tokenResult);

Response Example:

{
  "success": true,
  "token": "ftr12d4e830283b647d4b3b2a3d65f02b8ab"
}

Upgrade Token (Optional)

If you need to store the payment method and/or provision a network token for it, you must use the /upgrade endpoint.

Calling this endpoint creates a new multi-use token and invalidates the existing single-use token along with its CVC. You can also choose to provision a network token during the upgrade, allowing Forter to use it later during authorization.

Example Request

{
  "token": "ftr1d8a56cfa6b3745a39e4a42d5ab1048c8",
  "networkToken": {
    "provision": true
  }
}

Example Response

{
  "token": "ftr1efsdfew54wetg54ugdn58ns0482ko",
  "networkTokenStatus": {
    "created": true
  }
}

Create Payment

Include a unique idempotency-key header (e.g. a UUID) on each request. Reusing the same key for a retry ensures we return the original result instead of executing the operation again.

What is idempotency? Idempotency guarantees that making the same request multiple times has the same effect as making it once. It matters because payment requests can be retried due to network timeouts, client retries, or webhook redelivery. Without idempotency, a single charge could be processed twice, double-billing the customer.

POST /api/payments

Initiates a payment. Forter performs fraud check, routing, and authorization.

orderId is a required field — pass the merchant order ID to link the payment to fraud assessment

forterTokenString is the token generated in the previous section

amount field is expressed in cents

Set confirm: true for immediate capture

Set captureMethod to automatic or manual

Execute 3DS (If Required)

If Forter determines that 3DS is recommended or required, the payment create response will include a 3DS SDK token. You'll need to pass this token to the frontend so it can run the 3DS flow.

Example Response (With 3DS SDK token)

{
  "status": "requires_action",
  "nextAction": {
    "type": "use_sdk",
    "useSdk": {
      "token": "sdk_token_123"
    }
  }
}

3DS SDK Usage

await window.checkoutTools.managedOrders.manageOrder(
  managedOrderToken,
  {
    challengeContainer: () => {
      // render custom container for challenge modal if needed
      return htmlElement; // can be null to render Forter's default modal
    }
  }
);

Authorize Payment

POST /api/payments/:id/confirm

Used in case of confirm: false.

Example Response

{
  "id": "string",
  "amount": 9876,
  "amountReceived": 9876,
  "created": "2025-07-14T12:34:56.789Z",
  "currency": "AUD",
  "status": "succeeded",
  "connector": "adyen",
  "captureMethod": "automatic",
  "paymentMethod": "card",
  "paymentMethodType": "string"
}

In case 3DS is required before another authorization, the confirm response will include a 3DS SDK token.

Cancel Payment

POST /api/payments/:id/cancel

Cancel a payment that has not yet been captured. The reason field is optional.

Example Request

{
  "reason": "requested_by_customer"
}

Capture Payment

POST /api/payments/:id/capture

Used only if captureMethod was set to manual in /api/payments. The amountToCapture is optional and should be provided only for partial captures.

Example Request

{
  "amountToCapture": 1000
}

Example Response

{
  "id": "string",
  "amount": 9876,
  "amountReceived": 9876,
  "created": "2025-07-14T12:34:56.789Z",
  "currency": "AUD",
  "status": "succeeded",
  "connector": "adyen",
  "captureMethod": "automatic",
  "paymentMethod": "card",
  "paymentMethodType": "string"
}

:::

{
  "id": "string",
  "amount": 9876,
  "amountReceived": 9876,
  "created": "2025-07-14T12:34:56.789Z",
  "currency": "AUD",
  "status": "succeeded",
  "connector": "adyen",
  "captureMethod": "automatic",
  "paymentMethod": "card",
  "paymentMethodType": "string"
}

Example Response

{
  "orderId": "{{orderId}}",
  "amount": 1099,
  "currency": "USD",
  "captureMethod": "automatic",
  "confirm": true,
  "paymentMethod": {
    "type": "token",
    "forterTokenString": "{{token}}"
  },
  "connectionInformation": {
    "customerIP": "127.0.0.2"
  },
  "browserInfo": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  },
  "cartItems": [
    {
      "name": "testItem",
      "price": 1099,
      "quantity": 1,
      "type": "TANGIBLE"
    }
  ],
  "shipping": {
    "deliveryMethod": "Standard",
    "deliveryType": "DIGITAL"
  },
  "customer": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Smith"
  }
}

Refunds

Full Refund

Issue a reversal for a captured payment. Omit amount for a full refund.

Forter automatically determines the correct operation based on the transaction's settlement status — if the payment has not yet settled with the PSP, Forter will execute a void on your behalf. If it has settled, a refund is issued. This distinction is handled internally and requires no changes to your integration.

Note: This behavior is particularly relevant for PSPs, where sending a refund against an unsettled transaction would otherwise result in a failure at the PSP level.

Partial Refund

To issue a partial refund, include the amount field in your request. Forter will apply the same settlement-status check — if the transaction has settled, the partial refund is processed normally. If the transaction has not yet settled, partial refunds are not possible and Forter will return an error. In that case, you can wait for the next settlement cycle — once the transaction has settled (according to your settlement cycles), retry the partial refund using POST /api/refunds

POST /api/refunds

Example Request

{
  "paymentId": "{{paymentId}}",
  "amount": 500,
  "reason": "requested_by_customer"
}

Example Response

{
  "id": "ref_abc123",
  "amount": 500,
  "currency": "USD",
  "status": "succeeded",
  "reason": "requested_by_customer",
  "createdAt": "2025-07-14T12:34:56.789Z"
}

You can also retrieve refund details using GET /api/refunds/{id} or list all refunds for a payment using GET /api/refunds?paymentId={paymentId}.

Automatic Retry Logic – Predictive Payment Routing (PPR)

If the selected PSP declines or fails, Forter automatically generates a new routing recommendation:

The previous PSP + failure reason is sent to PPR

The next best PSP is returned based on live success metrics

Forter retries authorization with the new PSP transparently

Retries are idempotent and bounded by configurable limits

This is an internal process and does not require any merchant action.

Webhooks

Forter delivers asynchronous updates for every lifecycle event:

Event Type	Description
payment.authorized	Payment successfully authorized
payment.captured	Funds successfully captured
payment.failed	Payment or capture failed
payment.cancelled	Payment was cancelled (by merchant or by Forter)
refund.succeeded	Refund processed successfully
refund.failed	Refund failed to process

Example Webhook Payload

{
  "type": "payment.authorized",
  "eventId": "123456",
  "timestamp": "2024-11-07T05:31:56Z",
  "data": {
    "paymentId": "PAY-9981",
    "processor": "adyen"
  }
}

Forter webhooks include x-forter-signature and x-forter-timestamp headers for validation.

Implementation Notes

Forter's Hosted Fields must be used for PCI compliance - merchants are never exposed to raw PCI data

Single-use Forter Token expires within a maximum of 24 hours. In case the customer chooses to store the payment method, you can upgrade to a long-lived token using the Forter Tokenization API

Each transaction is idempotent by idempotency key to prevent double charges