Merchant & Identifiers

The merchant account

A merchant account is the root entity in AccruPay. All transactions, connected provider accounts, customers, and payment plans belong to a single merchant. Your API credentials are scoped to your merchant account.

Your identifiers vs AccruPay identifiers

AccruPay generates its own UUIDs for every resource. But for most operations, you also supply your own identifier — a string you control — so you can correlate AccruPay records with your own database without storing AccruPay IDs.

merchantInternalTransactionCode

Your transaction or order ID. A string you define.

const session = await sdk.transactions.clientSessions.payments.start({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  data: {
    merchantInternalTransactionCode: 'order-8821',
    amount: 4999n,
    currency: CURRENCY.USD,
    // ...
  },
});

This field is an idempotency key. A merchantInternalTransactionCode you have used before is rejected — AccruPay will not create a second session or transaction for it, regardless of the earlier one's status. This makes retries safe: a duplicate request cannot double-charge. To retry after a failed attempt, use a new code. See Idempotency.

It also enables recovery. If you lose the session ID, you can verify by your own code:

const transaction = await sdk.transactions.clientSessions.payments.verify({
  merchantInternalTransactionCode: 'order-8821',
});

And it is the primary reconciliation key: match AccruPay transactions to your database rows using the code you set.

tip

Use your existing order ID or database primary key. Do not generate a separate ID just for AccruPay — keeping these in sync adds complexity with no benefit.

merchantInternalCustomerCode

Your customer ID. A string you define.

Passed via the customer field in session and transaction requests:

const session = await sdk.transactions.clientSessions.payments.start({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  data: {
    customer: {
      merchantInternalCustomerCode: 'user-4412',
    },
    // ...
  },
});

AccruPay creates a provider-side customer record the first time a session with this code is completed. Subsequent sessions with the same code reuse that customer record.

This identifier is required for stored payment methods and payment plans. Without a customer record, there is no entity to attach the payment method to.

tip

Use your existing user ID or external customer identifier (for example, a CRM ID). This makes it trivial to look up stored payment methods and plans by customer without maintaining a separate mapping table.

merchantInternalPaymentPlanCode

The same pattern applies to payment plans. Supply your own plan identifier so you can correlate AccruPay plans to your subscription records:

data: {
  merchantInternalPaymentPlanCode: 'sub-1099',
  // ...
}

Connected provider accounts

Each payment provider you connect in the AccruPay dashboard gets its own UUID: the merchantTransactionProviderId. This is distinct from the transactionProvider enum (which identifies the provider type). The merchantTransactionProviderId identifies the specific account you connected.

You pass it when you need to select a specific provider account, for example when you have multiple accounts with the same provider:

data: {
  merchantTransactionProviderId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  // ...
}

Find this UUID in your AccruPay dashboard under connected providers.