Provider Routing

AccruPay is an orchestration layer. Your application calls one API; AccruPay routes the operation to whichever payment provider is configured on your account. You do not integrate with providers directly — you integrate with AccruPay once, and routing is a configuration concern.

This means you can add providers, switch between them, or run multiple providers simultaneously without changing application code.

How routing works

When you start a session, AccruPay uses the routing parameters in your request to determine which provider receives the operation. AccruPay then fetches that provider's configuration, initializes the session on the provider's platform, and returns a unified session object to your server.

The React SDK uses the session's token and payload to load the correct provider UI — automatically, without any provider-specific code in your application.

Three routing modes

1. Route by provider type

Pass a transactionProvider enum to select a category of provider. AccruPay routes to the configured account of that type on your merchant profile.

import AccruPay, { TRANSACTION_PROVIDER, CURRENCY, COUNTRY_ISO_2 } from '@accrupay/node';

const sdk = new AccruPay({ apiSecret: process.env.ACCRUPAY_API_SECRET });

const session = await sdk.transactions.clientSessions.payments.start({
  // TRANSACTION_PROVIDER enum values correspond to connected provider names.
  // Available values are listed in the Provider Integrations section.
  transactionProvider: TRANSACTION_PROVIDER[process.env.ACCRUPAY_PROVIDER_TYPE as keyof typeof TRANSACTION_PROVIDER],
  data: {
    amount: 5000n,
    currency: CURRENCY.USD,
    customer: { merchantInternalCustomerCode: 'customer-123' },
    merchantInternalTransactionCode: 'order-789',
    billing: {
      billingFirstName: 'Ana',
      billingLastName: 'Souza',
      billingEmail: 'ana@example.com',
      billingAddressCountry: COUNTRY_ISO_2.US,
    },
    storePaymentMethod: false,
  },
});

Use this when you have one account per provider type and want to select by capability. The enum values for TRANSACTION_PROVIDER are listed in the Provider Integrations section in the sidebar.

2. Route by provider account UUID

Pass merchantTransactionProviderId — the UUID of a specific connected provider account — to target an exact account. This is useful when you have multiple accounts at the same provider type (for example, separate accounts per region or per currency).

const session = await sdk.transactions.clientSessions.payments.start({
  merchantTransactionProviderId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  data: {
    amount: 4200n,
    currency: CURRENCY.EUR,
    merchantInternalCustomerCode: 'customer-456',
    merchantInternalTransactionCode: 'order-321',
    billing: {
      billingFirstName: 'Klaus',
      billingLastName: 'Bauer',
      billingEmail: 'klaus@example.com',
      billingAddressCountry: COUNTRY_ISO_2.DE,
    },
    storePaymentMethod: false,
  },
});

note

transactionProvider and merchantTransactionProviderId are mutually exclusive. Passing both in the same request is a validation error. Use one or the other — not both.

3. Omit routing parameters (default provider)

If you omit both transactionProvider and merchantTransactionProviderId, AccruPay routes to the default provider configured on your merchant account.

const session = await sdk.transactions.clientSessions.payments.start({
  // No transactionProvider or merchantTransactionProviderId
  data: {
    amount: 1500n,
    currency: CURRENCY.GBP,
    merchantInternalCustomerCode: 'customer-789',
    merchantInternalTransactionCode: 'order-654',
    billing: {
      billingFirstName: 'Sarah',
      billingLastName: 'Jones',
      billingEmail: 'sarah@example.com',
      billingAddressCountry: COUNTRY_ISO_2.GB,
    },
    storePaymentMethod: false,
  },
});

This is the simplest option if your account has one active provider.

Provider base config

When the React SDK initializes, it automatically fetches the provider-specific base config for the session using the token returned by start(). This config tells the SDK which UI components to load and how to authenticate with the provider's frontend SDK.

You do not handle this step. It happens inside the <AccruPay> provider component before the checkout form renders.

Switching providers

To route a transaction to a different provider, change the transactionProvider enum value or merchantTransactionProviderId UUID in your start() call. The rest of your application — the React SDK markup, the verify() call, your database schema — stays the same.

// Before: routed to provider A
transactionProvider: TRANSACTION_PROVIDER.PROVIDER_A,

// After: routed to provider B — zero other changes
transactionProvider: TRANSACTION_PROVIDER.PROVIDER_B,

This is the core promise of orchestration: provider-specific integration complexity is AccruPay's responsibility, not yours.

Common mistakes

Hardcoding provider UUIDs in application logic. UUIDs for provider accounts should come from environment configuration, not be embedded in code. This makes it straightforward to use different provider accounts across environments (sandbox vs. production).

Passing both routing fields. transactionProvider and merchantTransactionProviderId are mutually exclusive. Pick the one that fits your routing model.

Assuming the same UUID across environments. Provider account UUIDs differ between sandbox and production. Always load the UUID from environment-specific config.