Merchant Managed

This guide provides enterprise merchants with a comprehensive integration path for Forter's Orchestration service, enabling unified payment processing with built-in fraud protection, predictive routing, and 3DS handling. The Orchestration API consolidates multiple payment operations into a single, cohesive workflow that replaces traditional PSP-specific integrations while maintaining enterprise-grade reliability and performance.

Integration Flow

flowchart TD
    A["Customer enters card details"] --> B["Phase 1: Hosted Fields Tokenization"]
    B --> C["Phase 2: Pre-Authorization Fraud Check"]
    C --> D{"Fraud Decision"}
    D -- Decline --> E["Reject Transaction"]
    D -- "Managed Order Token" --> F["Execute 3DS"]
    D -- Approve --> G["Phase 3: Create Payment"]
    F --> H["Handle 3DS Challenge"]
    H --> I{"Challenge Success?"}
    I -- No --> E
    I -- Yes --> G
    G --> L["Phase 4: Capture Payment"]

Phase 1: Hosted Fields Integration (Tokenization)

Securely capture payment credentials using Forter's Hosted Fields, replacing PSP-native checkout fields.

1.1 Backend Session Key Generation

Generate an authentication token for the frontend to initialize Hosted Fields.

Endpoint: POST /v1/tokenization/client-key

// Node.js example
router.get('/client-key', async (req, res) => {
  const authString = Buffer.from(
    `${FORTER_SITE_ID}:${FORTER_SITE_SECRET}`
  ).toString('base64')
  const authorization = `Basic ${authString}`

  const response = await axios({
    method: 'POST',
    url: `${baseUrl}/v1/tokenization/client-key`,
    headers: {
      Authorization: authorization,
      'Content-Type': 'application/json',
    },
    data: { ttlMinutes: 60 },
  })

  res.json({ token: response.data.clientKey })
})

1.2 Frontend SDK Initialization

Include Forter's SDK on your checkout page:

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

Initialize and configure Hosted Fields:

const forterCollect = await window.checkoutTools.collect.init({
  environment: 'production',
  authToken: await getAuthToken(),
  onValidityChange: (fieldId, isValid, error) =>
    updateFieldValidation(fieldId, isValid, error),
  onCardBrandChange: (cardBrand) => updateCardBrandDisplay(cardBrand),
})

await forterCollect.addFields({
  'card-holder-name': {
    type: 'CARD_HOLDER_NAME',
    placeholder: 'Name on card',
    style: getFieldStyles(),
  },
  'card-number': {
    type: 'CARD_NUMBER',
    placeholder: '1234 5678 9012 3456',
    style: getFieldStyles(),
  },
  'card-expiry': {
    type: 'CARD_EXPIRATION_DATE',
    placeholder: 'MM/YY',
    style: getFieldStyles(),
  },
  'card-cvc': {
    type: 'CARD_CVC',
    placeholder: 'CVC',
    style: getFieldStyles(),
  }
})

1.3 Token Submission

const handlePaymentSubmit = async (formData) => {
  const tokenResult = await forterCollect.submit();
  if (!tokenResult.success) {
    handleValidationErrors(tokenResult.errors);
    return;
  }
  await processPayment({ ...formData, forterToken: tokenResult.token });
};

1.3.1 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
  }
}

Phase 2: Pre-Authorization Fraud Check

Prevent fraud before initiating payment authorization.

2.1 Order Creation

Endpoint: POST /v3/orders

Payload includes:

Order ID

Forter token

Cart and pricing details

Customer + billing/shipping info

Response:

decision: APPROVE / DECLINE

reason: (optional explanation)

forterDecisionCorrelationId: Correlation ID to be passed to Phase 3 payment creation

Or, in case Forter recommends 3DS the response will include:

Managed order token

forterDecisionCorrelationId: Correlation ID to be passed to Phase 3 payment creation

2.2 Decision Logic

APPROVE → proceed to payment

DECLINE → reject transaction

Managed Order Token → Execute 3DS

Phase 3: Payment Processing via Orchestration

Execute payments through Forter's unified orchestration layer with 3DS and routing support.

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.

3.1 Create Payment

Endpoint: POST /api/payments

Include the Forter orderId from Phase 2 in the request body to link the payment to the prior fraud assessment.

The forterDecisionCorrelationId field is required for Merchant Managed integrations. It links the payment to the pre-authorization fraud decision obtained in Phase 2, enabling Forter to correlate the authorization with the risk assessment.

If the Phase 2 order creation response includes a managedOrderToken, you must pass it in the Create Payment request.

Request fields:

orderId — The Forter order ID from Phase 2

amount — Payment amount in smallest currency unit (e.g. cents)

currency — ISO 4217 currency code (e.g. usd)

captureMethod — automatic for immediate capture or manual for a manual capture

confirm — Set to true for immediate authorization or set to false to send another confirm call before authorization

forterDecisionCorrelationId — Correlation ID from the Phase 2 fraud decision response

managedOrderToken — If returned in the Phase 2 response, must be included here

paymentMethod.type — Payment method type (e.g. token)

paymentMethod.forterTokenString — The Forter token obtained from Phase 1

connectionInformation.customerIp — IP address of the customer

browserInfo.userAgent — User agent string of the customer's browser

cartItems — List of cart items, each with name, price, quantity, and type

shipping.deliveryMethod — Delivery method (e.g. standard)

shipping.deliveryType — Delivery type (e.g. digital)

customer.email — Customer email address

customer.firstName — Customer first name

customer.lastName — Customer last name

{
  "orderId": "{{orderId}}",
  "amount": 1099,
  "currency": "USD",
  "captureMethod": "automatic",
  "confirm": true,
  "forterDecisionCorrelationId": "{{correlationId}}",
  "managedOrderToken": "{{managedOrderToken}}",
  "paymentMethod": {
    "type": "token",
    "forterTokenString": "{{paymentToken}}"
  },
  "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"
  }
}

Response fields:

id — Unique payment ID

orderId — The order ID associated with this payment

amount — Requested payment amount

amountReceived — Amount actually received/authorized

createdAt — ISO 8601 timestamp of payment creation

currency — ISO 4217 currency code

status — Payment status: authorized, failed

connector — The PSP/connector used (e.g. stripe, adyen)

captureMethod — automatic or manual

paymentMethodType — Type of payment method used (e.g. card)

metadata — Additional metadata key-value pairs

{
  "id": "string",
  "orderId": "order-abc-123",
  "amount": 9876,
  "amountReceived": 9876,
  "createdAt": "2025-07-14T12:34:56.789Z",
  "currency": "GBP",
  "status": "authorized",
  "connector": "stripe",
  "captureMethod": "automatic",
  "paymentMethodType": "card",
  "metadata": {}
}

3.2 Confirm Payment

Use this step when confirm was set to false.

Endpoint: POST /api/payments/:id/confirm

Response returns final status: authorized or failed

3.3 Capture Authorized Payment

Use this step when captureMethod was set to manual.

Endpoint: POST /api/payments/:id/capture

{
  "amount": 1099
}

3.4 Cancel Payment

Cancel a payment that has not yet been captured.

Endpoint: POST /api/payments/:id/cancel

{
  "reason": "requested_by_customer"
}

Phase 4: 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

Endpoint: POST /api/refunds

{
  "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}.

Phase 5: 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.

Phase 6: 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.

Phase 7: 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