Merchant Managed - Overviews

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 Integration Flow

Decline
Managed Order Token
Approve
No
Yes
Customer enters card details
Phase 1: Hosted Fields Tokenization
Phase 2: Pre-Authorization Fraud Check
Fraud Decision
Reject Transaction
Execute 3DS
Phase 3: Create Payment
Handle 3DS Challenge
Challenge Success?
Phase 4: Capture Payment

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) 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 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 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 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) 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 Phase 2: Pre-Authorization Fraud Check

Prevent fraud before initiating payment authorization.

2.1 Order Creation 2.1 Order Creation

Endpoint: POST /v3/orders

Payload includes:

Response:

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

2.2 Decision Logic 2.2 Decision Logic

Phase 3: Payment Processing via Orchestration 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.

3.1 Create Payment 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": "{{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": "customer@example.com",
    "firstName": "John",
    "lastName": "Smith"
  }
}

3.2 Confirm Payment 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 3.3 Capture Authorized Payment

Use this step when captureMethod was set to manual.

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

{
  "amount": 10993
}

3.4 Cancel Payment 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 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) Phase 5: Automatic Retry Logic – Predictive Payment Routing (PPR)

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

  1. The previous PSP + failure reason is sent to PPR
  2. The next best PSP is returned based on live success metrics
  3. Forter retries authorization with the new PSP transparently
  4. Retries are idempotent and bounded by configurable limits

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

Phase 6: Webhooks 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 Phase 7: Implementation Notes