Customers

What is an AccruPay customer?

An AccruPay customer is a record that links your internal customer identifier (merchantInternalCustomerCode) to a customer record in a connected provider account. It is the entity that stored payment methods and payment plans are attached to.

Provider scope

A customer is scoped to a specific connected provider account. If you have two provider accounts connected to AccruPay, a customer record in one account is separate from a customer record in the other. Stored payment methods and payment plans are therefore also scoped to the provider account where they were created.

Auto-creation

The most common path: pass the customer field when starting a session, and AccruPay creates the provider-side customer record automatically when the session is completed.

const session = await sdk.transactions.clientSessions.payments.start({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  data: {
    customer: {
      merchantInternalCustomerCode: 'user-4412',
    },
    amount: 4999n,
    currency: CURRENCY.USD,
    merchantInternalTransactionCode: 'order-8821',
    billing: {
      billingFirstName: 'Jane',
      billingLastName: 'Smith',
      billingEmail: 'jane@example.com',
      billingAddressCountry: COUNTRY_ISO_2.US,
    },
    storePaymentMethod: true,
  },
});

After the session completes, the customer exists and the stored payment method is attached to it.

note

The deprecated merchantInternalCustomerCode top-level field has the same effect but is superseded by the customer selector field shown above. Prefer customer: { merchantInternalCustomerCode } in new integrations.

Explicit creation

You can also create or look up customers outside of a payment flow using the customers service.

note

The @accrupay/node SDK customers service currently exports type fragments only. Full customer mutation support may require raw GraphQL queries against the merchant API. Check the GraphQL API reference for the current mutation signatures.

Customer fields

Field	Type	Description
`id`	UUID	AccruPay-generated identifier
`merchantInternalCustomerCode`	string	Your customer ID
`providerCode`	string	The provider's internal customer ID
`email`	string	Customer email
`firstName`	string	First name
`lastName`	string	Last name
`phone`	string	Phone number
`address`	object	Billing address
`status`	enum	Customer status in the provider system

Referencing a customer in requests

Use the MerchantCustomerSelector type — an object with your customer code — wherever AccruPay asks for a customer reference:

const customer: MerchantCustomerSelector = {
  merchantInternalCustomerCode: 'user-4412',
};

This selector is accepted in session start requests, server-side charge requests, and payment plan creation.

Why customers matter

Customers are required for:

Stored payment methods — a payment method must be associated with a customer record
Payment plans — recurring billing is linked to a customer and their stored payment method
Server-side charges — charging a stored card requires a customer with an attached payment method

For one-off guest payments where you do not intend to store the card, you can omit the customer field entirely.

What is an AccruPay customer?​

Provider scope​

Auto-creation​

Explicit creation​

Customer fields​

Referencing a customer in requests​

Why customers matter​

Next steps​