Save a Card

AccruPay supports two approaches for saving a customer's card for future use. Choose based on whether you want to charge immediately or just vault the card.

Prerequisite

Saving a card always requires a customer with a merchantInternalCustomerCode so the payment method can be associated with that customer.

Which approach to use

	Method A: Save during payment	Method B: Dedicated add-card session
Charges the customer	Yes	No
When to use	Charge now + save for later	Onboarding, subscription setup, 0-amount vault
Extra API calls	None (same session)	One additional session start

tip

Use Method A when you want to charge immediately and save the card for future use. Use Method B when you want to save a card without charging — for example, during onboarding or subscription setup.

---

Method A: Save during a payment session

Set storePaymentMethod: true in the session start call. The card is saved automatically when the payment succeeds.

1. Start the session (server)

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({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  data: {
    merchantInternalTransactionCode: 'txn_123',
    amount: 10000n, // $100.00
    currency: CURRENCY.USD,
    storePaymentMethod: true, // <-- save the card on success
    customer: {
      merchantInternalCustomerCode: 'customer_abc',
    },
    billing: {
      billingFirstName: 'Jane',
      billingLastName: 'Smith',
      billingEmail: 'jane@example.com',
      billingAddressCountry: COUNTRY_ISO_2.US,
    },
  },
});

BigInt amounts

Amounts are bigint in the smallest currency unit. 10000n = $100.00.

2. Render the checkout form (frontend)

Pass session.id to the React SDK — the form is identical to a regular checkout.

import {
  AccruPay,
  CardholderName,
  CardNumber,
  CardExpiry,
  CardCVC,
  SubmitButton,
} from '@accrupay/react';

function SaveCardCheckout({ sessionId }: { sessionId: string }) {
  return (
    <AccruPay
      merchantPublicId={process.env.NEXT_PUBLIC_ACCRUPAY_MERCHANT_ID!}
      transactionSessionId={sessionId}
    >
      <CardholderName placeholder="Full name on card" />
      <CardNumber />
      <CardExpiry />
      <CardCVC />
      <SubmitButton onSuccess={(result) => console.log('Paid & saved', result)}>
        Pay and save card
      </SubmitButton>
    </AccruPay>
  );
}

3. Verify and retrieve the saved payment method (server)

import { TRANSACTION_STATUS } from '@accrupay/node';

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

if (transaction.status === TRANSACTION_STATUS.SUCCEEDED) {
  // The saved payment method is on the transaction
  const savedMethodId = transaction.paymentMethod?.id;

  // Persist savedMethodId against your customer record
  await db.customers.update('customer_abc', {
    defaultPaymentMethodId: savedMethodId,
  });
}

---

Method B: Dedicated add-card session (no charge)

Use clientSessions.paymentMethod.add when you want to vault a card without charging.

1. Start the add-card session (server)

The add-card session does not take amount or storePaymentMethod fields.

const session = await sdk.transactions.clientSessions.paymentMethod.add.start({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  data: {
    merchantInternalTransactionCode: 'add_pm_456',
    currency: CURRENCY.USD,
    customer: {
      merchantInternalCustomerCode: 'customer_abc',
    },
    billing: {
      billingFirstName: 'Jane',
      billingLastName: 'Smith',
      billingEmail: 'jane@example.com',
      billingAddressCountry: COUNTRY_ISO_2.US,
    },
  },
});

2. Render the card form (frontend)

Same React SDK components — the customer enters their card details but is not charged.

import {
  AccruPay,
  CardholderName,
  CardNumber,
  CardExpiry,
  CardCVC,
  SubmitButton,
} from '@accrupay/react';

function AddCardForm({ sessionId }: { sessionId: string }) {
  return (
    <AccruPay
      merchantPublicId={process.env.NEXT_PUBLIC_ACCRUPAY_MERCHANT_ID!}
      transactionSessionId={sessionId}
    >
      <CardholderName placeholder="Full name on card" />
      <CardNumber />
      <CardExpiry />
      <CardCVC />
      <SubmitButton onSuccess={() => console.log('Card saved')}>
        Save card
      </SubmitButton>
    </AccruPay>
  );
}

3. Verify and retrieve the saved payment method (server)

const transaction = await sdk.transactions.clientSessions.paymentMethod.add.verify({
  merchantInternalTransactionCode: 'add_pm_456',
});

// transaction.action === 'ADD_PAYMENT_METHOD'
const savedMethodId = transaction.paymentMethod?.id;

// Persist this ID for future charges
await db.customers.update('customer_abc', {
  defaultPaymentMethodId: savedMethodId,
});

---

Next steps

• Charge a Stored Card — use the saved paymentMethod.id for future charges