OrchestratorMerchant API

The OrchestratorMerchant class is the primary interface for integrating Payen Hosted Payment Components (HPC) into your payment form. It manages component initialization and session key generation.

Importing

Import OrchestratorMerchant as an ES module from the provided script URL:

import {OrchestratorMerchant} from "https://prprocessing.trustpayglobal.com/hosted-component/scripts/merchant/orchestrator.esm.js"; 

info

We've used the sandbox endpoint https://prprocessing.trustpayglobal.com in the examples. Please replace this with the endpoint provided by your Payen onboarding contact for production deployments.

Constructor

Create an instance by passing a configuration object:

const orchestrator = new OrchestratorMerchant(config);

Parameters

Parameter	Type	Required	Description
config	Object	Yes	Configuration object defining the initialization endpoint, fields to render, and optional customizations. See Customizations for full details.

Initialization Behaviour

The constructor returns immediately while the components load asynchronously. Each container element dispatches an hpc.initializationComplete event when its field is ready. See Events for details.

Constructor Errors

The constructor will throw an exception in the following cases:

• A configured container ID is not found in the DOM (e.g., a misspelled or missing element).
• No fields are configured in the configuration object.

Wrap the constructor call in a try/catch block to handle these errors gracefully:

let orchestrator;
try {
   orchestrator = new OrchestratorMerchant(config);
} catch (error) {
   console.error("Failed to initialize HPC components:", error);
   // Handle the error — e.g., display a fallback payment form or alert the user
}

Errors are thrown as Error() objects with description formed by the concatenation of the error code and its description separated with a colon, for example missing.field: Unable to locate the placeholder container with an id of exampleCardNumber.

Code	Description
missing.config	The supplied fieldConfig was missing or invalid
missing.field	Unable to locate the placeholder container with an id of {id}
no.fields	At least one field must be configured
invalid.field	Field config is invalid
invalid.field.id	Field member id is invalid
invalid.field.aria	Field member aria is invalid
invalid.field.autocomplete	Field member autocomplete is invalid
invalid.field.maxLength	Field member maxLength is invalid
invalid.field.minLength	Field member minLength is invalid
invalid.field.placeholder	Field member placeholder is invalid
invalid.field.title	Field member title is invalid
invalid.merchantId	Missing merchantId
invalid.feedback.valid	Feedback class valid is invalid
invalid.feedback.invalid	Feedback class invalid is invalid
invalid.feedback.empty	Feedback class empty is invalid
invalid.feedback.focusd	Feedback class focus is invalid
invalid.style.caret-color	Style caret-color is invalid
invalid.style.color	Style color is invalid
invalid.style.font-family	Style font-family is invalid
invalid.style.font-size	Style font-size is invalid
invalid.style.font-style	Style font-size is invalid
invalid.style.font-weight	Style font-weight is invalid
invalid.style.letter-spacing	Style letter-spacing is invalid
invalid.style.line-height	Style line-height is invalid
invalid.style.text-align	Style text-align is invalid
invalid.style.text-transform	Style text-transform is invalid

warning

If a component fails to load due to network issues after successful construction, no explicit error event is dispatched. To guard against stalled initializations, consider implementing a timeout that triggers if hpc.initializationComplete events are not received within an expected timeframe (e.g., 5–10 seconds).

Multiple Instances

Technically, you can create multiple instances of OrchestratorMerchant on the same page, provided that container IDs are unique between each instance. However, this practice is strongly discouraged and not recommended.

Displaying multiple payment forms simultaneously would be confusing for users and could lead to integration errors (e.g., calling startSession() on the wrong orchestrator). If your use case requires conditional payment flows, consider showing/hiding a single form or re-initializing components dynamically using remove().

Methods

startSession()

Instructs all active HPC components to tokenize their current contents and returns a session key for each field. This is the method you call when the user submits the payment form (e.g., clicks your Pay button).

Signature

orchestrator.startSession()
   .then((sessions) => { ... })
   .catch((error) => { ... });

Returns

A Promise that resolves to a Map where:

• Keys are field type names ("cardNumber", "expiryDate", "cvv").
• Values are unique session key strings representing the tokenized card data.

warning

Session keys are ephemeral and expire approximately 60 seconds after creation. Ensure your backend forwards them to the Payen Direct API promptly. If a session key has expired, the authentication request will fail.

Error conditions

The promise rejects when it is unable to create a session key for any of the configured fields. This can occur if there is a networking issue, or should any of the fields be empty. It is recommended to use the validity events to ensure that startSession is only called when all the fields are valid.

Usage Example

document.getElementById('examplePay').addEventListener('click', (e) => {
   orchestrator.startSession()
      .then((sessions) => {
         // Extract session keys from the Map
         const cardNumberKey = sessions.get("cardNumber");
         const expiryDateKey = sessions.get("expiryDate");
         const cvvKey = sessions.get("cvv");

         // Send session keys to your server for payment processing
         fetch('/api/payment', {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({
               cardNumber: cardNumberKey,
               expiryDate: expiryDateKey,
               securityCode: cvvKey
            })
         });
      })
      .catch((error) => {
         console.warn("startSession failed:", error);
         // Handle the error — e.g. show a message to the user
      });

   e.preventDefault();
});

Your backend endpoint should then forward these session keys to the Payen Direct API authentication entry point. See Call Direct API for the exact request structure.

warning

Session keys are PCI-sensitive data. Never log or store them persistently. Use HTTPS transport for all communication involving session keys.

remove()

Cleans up all HPC resources, including detaching message listeners and removing iframe elements from their containers. Call this method if you need to tear down the payment form (e.g., user cancels and navigates away).

Signature

orchestrator.remove();

info

After calling remove(), the orchestrator instance should not be reused. Create a new OrchestratorMerchant instance if you need to re-initialize components.

See Also

• Introduction — Overview of how HPC works and its key features.
• Quick Start — Step-by-step guide to embedding HPC fields
• Customizations — Full reference for configuration options and styling
• Events — Custom DOM events dispatched by HPC components
• Message Flow — Detailed sequence of interactions in the payment flow