Aras Payment Checkout Widget

Card and ACH checkout for the Aras Payment API. Use this package in your front-end to offer card and ACH payments with surcharging and optional Level 2/3 data.

Install

npm install araspayment-checkout-widget

Note: The payment SDK is automatically installed and loaded (npm import or CDN). You don't need to add any script tags or CSS manually.

API client (framework-agnostic)

Use the client in Node or the browser for config, quotes, payments, or status checks.

const { createCheckoutClient } = require('araspayment-checkout-widget');

const client = createCheckoutClient({
  apiBaseUrl: 'https://your-api.example.com',
  apiKey: 'optional-api-key',
  origin: 'https://your-store.example.com'  // optional in browser (defaults to window.location.origin)
});

// GET /config
const config = await client.getConfig(storeId);

// POST /surcharge/quote — amount in cents
const quote = await client.quoteSurcharge({
  storeId,
  referenceId: 'order-123',
  amount: 5000,
  currency: 'USD',
  method: 'card'
});

// GET /payment-methods — fetch available payment methods
const methods = await client.getPaymentMethods(storeId, {
  countryCode: 'US',
  shopperReference: 'customer-456'
});

// POST /payments — submit a payment (new card or stored)
const result = await client.submitPayment({
  storeId,
  referenceId: 'order-123',
  returnUrl: 'https://your-store.example.com/order/result',
  paymentMethod: { type: 'scheme', storedPaymentMethodId: 'XXXX' },
  shopperInteraction: 'ContAuth',
  recurringProcessingModel: 'CardOnFile',
  shopperReference: 'customer-456',
  countryCode: 'US'
});

// POST /payments/details — complete 3DS / redirect
const details = await client.submitPaymentDetails({ details: { /* ... */ } });

// GET /stored-payment-methods — list saved payment methods
const stored = await client.getStoredPaymentMethods(storeId, 'customer-456');

// POST /sessions — legacy session-based flow
const session = await client.createSession({
  storeId,
  referenceId: 'order-123',
  returnUrl: 'https://your-store.example.com/order/result',
  shopperReference: 'customer-456',
  countryCode: 'US',
  order: { customerReference: 'ORD-001', lineItems: [/* ... */] }
});

// GET /status/{referenceId}
const status = await client.getStatus(storeId, 'order-123');

Payment flows

New card / ACH payment (classic flow)

1. Widget calls GET /payment-methods to fetch available methods.
2. The payment form is rendered (via onSubmit callback).
3. On submit, widget calls POST /payments with encrypted card data.
4. If 3DS is required, the SDK handles the action via POST /payments/details.
5. Result is shown (success screen or error with refusal reason).

Stored payment method (token-based)

1. Widget calls GET /stored-payment-methods to list saved cards/ACH.
2. Saved methods are displayed as clickable cards (card: brand + last4 + expiry; ACH: bank name).
3. User clicks a saved method → a Pay button appears (no CVC or expiry fields).
4. Clicking Pay calls POST /payments with storedPaymentMethodId, shopperInteraction: 'ContAuth', and recurringProcessingModel: 'CardOnFile'.
5. If the payment is refused, the refusalReason is shown and the button resets.

Widget (browser-only)

Mount the full checkout flow (config → quote → payment methods → Pay) into a container:

const { initCheckout } = require('araspayment-checkout-widget');

initCheckout({
  environment: 'test',  // 'live' or 'test' (default: 'test')
  storeId: '123',
  apiKey: 'optional-api-key',
  container: '#checkout-container',
  amount: 5000,
  currency: 'USD',
  referenceId: 'order-123',
  returnUrl: 'https://your-store.example.com/order/result',
  shopperReference: 'customer-456',
  countryCode: 'US',
  order: { customerReference: 'ORD-001', lineItems: [/* ... */] },
  onSuccess(result) {
    console.log('Payment completed', result);
  },
  onError(err) {
    console.error('Payment error', err);
  }
});

| Option | Required | Description | |--------|----------|-------------| | environment | No | 'live' or 'test' (default: 'test'). Maps to https://api-pay.araspayment.com or https://api-develop.araspayment.com. | | apiBaseUrl | No | Custom API base URL. Overrides environment if provided. | | storeId | Yes | Store identifier. | | apiKey | No | Optional API key. | | container | Yes | DOM element or CSS selector. | | amount | No | Base amount in cents. | | currency | No | Default 'USD'. | | referenceId | No | Unique payment reference; default is a generated UUID. | | returnUrl | Yes | Redirect URL after payment. | | origin | No | Origin header; in browser defaults to window.location.origin. | | shopperReference | No | Shopper/customer identifier. | | countryCode | No | 2-letter country (e.g. US). | | order | No | Easy order object for Level 2/3; see Order format below. | | storePaymentMethod | No | Enable storing payment method for future use (default: true). Requires shopperReference. | | showStoredPaymentMethods | No | Use Drop-in to show stored payment methods (default: true). Requires shopperReference. Individual components don't show stored methods. | | showPaymentMethods | No | Show regular (not stored) payment methods (default: true). Set to false to only show stored card details. | | showSuccessScreen | No | Show built-in success screen after payment (default: true). Set to false to handle success entirely via onSuccess. | | showErrorScreen | No | Show built-in error screen on failure (default: true). Set to false to handle errors entirely via onError. | | onSuccess | No | Called with result on success; if omitted and returnUrl is set, redirects. | | onError | No | Called on error. |

Order format (Level 2/3)

For POST /payments you can send an optional order object so the backend maps it to enhanced scheme data (L2/L3). The widget and API client pass order through as-is; the backend performs the mapping.

All fields are optional. Amounts are in minor units (e.g. cents).

• Top level: customerReference (max 25; if omitted backend uses referenceId), orderDate (ISO YYYY-MM-DD), totalTaxAmount, freightAmount, dutyAmount, shipFromPostalCode.
• destination: countryCode (3-letter alpha-3, e.g. USA, CAN), postalCode, stateProvinceCode.
• lineItems[]: description, productCode, quantity, unitPrice, totalAmount, discountAmount, commodityCode, unitOfMeasure (lengths/format per scheme spec; backend trims and validates).

Full field details and examples: Checkout Widget API — Order format (Level 2/3) (backend API doc in this repo).

Widget API

The initCheckout function returns a widget API object with methods to interact with the payment form:

const widget = initCheckout({...});

// Check if form is valid
if (widget.isValid()) {
  // Form is ready to submit
}

// Trigger payment programmatically
widget.triggerPayment();

// Get the Pay button element
const payButton = widget.getPayButton();

// Get current quote
const quote = widget.getQuote();

See API_REFERENCE.md for complete API documentation.

Build

npm run build

Output: dist/araspayment-checkout-widget.esm.js, dist/araspayment-checkout-widget.cjs.js, dist/araspayment-checkout-widget.umd.js.

License

MIT