Skip to main content

SaaS Orchestration with Third-Party Vault

Merchants using OrchestratorX SaaS can still integrate an external PCI-compliant vault. This setup is ideal for merchants who already have existing token infrastructure (e.g., VGS, Tokenex and more).

Key Highlights​

  • Combines the scalability of SaaS orchestration with external vault flexibility.
  • Supports Vault Proxy APIs for tokenization/de-tokenization.
  • Merchant retains token portability across platforms.

Third party vault integration options​

Merchant managed client with external vault's card formThe merchant directly integrates with the external vault SDK and card data is captured and tokenized using the external vault SDK
OrchestratorX managed client with External Vault's card formThe External Vault SDK is loaded onto the OrchestratorX Unified Checkout SDK. The card data is captured and tokenized using the external vault SDK
OrchestratorX managed client with native card formIn this approach, the OrchestratorX SDK is used to capture card details, but card storage and tokenization are handled by an external vault

Configuring External Vault on OrchestratorX​

For External Vaults to work with OrchestratorX you need to configure the required API credentials on the OrchestratorX dashboard. You can do this by navigating to Orchestrator > Connector > Vault Processor and entering the required details.

1. OrchestratorX managed client and card form​

In this approach, the OrchestratorX SDK is used to capture card details, but card storage and tokenization are handled by an external vault. OrchestratorX backend orchestrates payments using tokens issued by the external vault.

New user payments flow

  1. Load the OrchestratorX Payments SDK via Payments Create API request . The end-user enters their payment credentials for the selected payment option
  2. The Payment Confirm API request containing the payment method is sent to the PSP from OrchestratorX
  3. Once the PSP responds with the outcome approved or declined along with the PSP token, OrchestratorX then proceeds to store and tokenize the card.
  4. The card is stored in external vault, which returns a vault_token
  5. Upon receiving the vault_token, OrchestratorX generates a payment_method_id. A payment_method_id is a versatile token and connects a lot of entities together like customer_id, psp_token, vault_token
  6. This payment_method_id is returned to the merchant via webhooks

Repeat user payments flow

  1. In a repeat-user payment, the OrchestratorX SDK will load the stored payment methods of the customer based the customer_id sent as part of the Payments Create API request .
  2. The end-user can select the desired payment option and add their CVV
  3. The SDK sends the Payment Confirm API request when the user hits Pay
  4. The OrchestratorX backend resolves the payment_method_id to identify available vault_token
    1. OrchestratorX can use the detokenize flow to obtain the raw card in exchange for the vault_token. It will then send payload with the raw card credential to the payment provider or PSP downstream.

Merchant Initiated Transaction (MIT) flow

  1. The merchant can perform the MIT or Recurring transactions using payment_method_id

2. OrchestratorX managed client with External Vault's card form​

In this flow, the External Vault SDK is layered directly onto the OrchestratorX Unified Checkout SDK. The External Vault SDK captures card details and tokenizes them immediately at the vault. This ensures that sensitive card data never touches the OrchestratorX server.

New user payments flow

  1. Load the OrchestratorX Payments SDK via Payments Create API request . The end-user enters their payment credentials for the selected payment option. The OrchestratorX SDK in-turn loads the external vault SDK that has been configured in the merchant account.
  2. The end-user enters their payment credentials for card payment method directly in the external vault SDK
  3. The external vault SDK returns a vault_token and associated card metadata to the OrchestratorX SDK
  4. The Payment Confirm API request containing the vault_token and associated card metadata is sent to OrchestratorX server by the OrchestratorX SDK
  5. OrchestratorX server then creates the PSP payload based on the payment providers or PSPs configured for the merchant
  6. This PSP Payload containing the vault_token is sent to the Proxy endpoint of the external vault
  7. The external vault replaces the vault_token with the raw card and sends the request to the PSP
  8. Once the PSP responds with the outcome approved or declined along with the PSP token, the Proxy endpoint of the external vault sends the response back to OrchestratorX server
  9. Upon receiving the vault_token, OrchestratorX generates a payment_method_id. A payment_method_id is a versatile token and connects a lot of entities together like customer_id, psp_token, vault_token
  10. This payment_method_id and vault_token are returned to the merchant via webhooks

Repeat user payments flow

  1. In a repeat-user payment, the OrchestratorX SDK will load the stored payment methods of the customer based the customer_id sent as part of the Payments Create API request.
  2. The end-user can select the desired payment option and add their CVV
  3. The SDK sends the Payment Confirm API request API request to the OrchestratorX server when the user hits Pay
  4. The OrchestratorX backend resolves the payment_method_id to identify available vault_token
    1. OrchestratorX can use the detokenize flow to obtain the raw card in exchange for the vault_token. It will then send payload with the raw card credential to the payment provider or PSP downstream.

Merchant Initiated Transaction (MIT) flow

  1. The merchant can perform the MIT or Recurring transactions using payment_method_id

3. Merchant managed client with external vault's card form​

The merchant integrates with external vault SDK which manages the card data and user experience entirely independent of the OrchestratorX. The card is tokenized directly with the chosen vault, after which merchant will have to pass the token returned by external vault along with the card metadata to OrchestratorX to process the payment.

New user payments flow

  1. Load the external vault SDK that has been integrated directly by the merchant.
  2. The end-user enters their payment credentials for card payment method directly in the external vault SDK.
  3. The external vault SDK returns a vault_token and associated card metadata.
  4. The merchant will use Payments Create API request to send the vault_token and associated card metadata to OrchestratorX server.
  5. OrchestratorX server then creates the PSP payload based on the payment providers or PSPs configured for the merchant
  6. This PSP Payload containing the vault_token is sent to the Proxy endpoint of the external vault
  7. The external vault replaces the vault_token with the raw card and sends the request to the PSP
  8. Once the PSP responds with the outcome approved or declined along with the PSP token, the Proxy endpoint of the external vault sends the response back to OrchestratorX server
  9. Upon receiving the vault_token, OrchestratorX generates a payment_method_id. A payment_method_id is a versatile token and connects a lot of entities together like customer_id, psp_token, vault_token
  10. This payment_method_id and vault_token are returned to the merchant via webhooks

Repeat user payments flow

  1. In a repeat-user payment, the merchant needs to load the stored payment methods of the customer based the customer_id sent as part of the Payment Method - List Customer Saved Payment Methods API request.
  2. The end-user can select the desired payment option and add their CVV. This CVV is entered directly into the elements provided by external vault.
  3. The external vault tokenizes the CVV temporarily and returns a temp_vault_token
  4. The merchant will use Payments Create API request to send the vault_token and the temp_vault_token of the card selected by the end user.
  5. OrchestratorX server then creates the PSP payload based on the payment providers or PSPs configured for the merchant
  6. This PSP Payload containing the vault_token and temp_vault_token is sent to the Proxy endpoint of the external vault
  7. The external vault replaces the vault_token with raw card, the temp_vault_token with CVV and sends the request to the PSP
  8. Once the PSP responds with the outcome approved or declined along with the PSP token, the Proxy endpoint of the external vault sends the response back to OrchestratorX server

Merchant Initiated Transaction (MIT) flow

  1. The merchant can perform the MIT or Recurring transactions using vault_token