StateSet API Docs

This walkthrough uses @stateset/embedded 1.39.0 to create a 25.00 USD payment record and a 12.50 USD refund record. It verifies retry behavior and two rejected refund requests in a fresh in-memory database.

These calls update local commerce records. They do not charge a card, contact a payment provider, or transfer a refund. The completion step below simulates a successful provider result so you can explore the lifecycle without credentials or money movement.

Prerequisites

Use Node.js 20.20.0+ and npm 10+. In a new directory:

mkdir stateset-payments-example
cd stateset-payments-example
npm init -y
npm install @stateset/embedded@1.39.0

See SDK installation if the native module cannot load.

Run the complete example

Save this as payments-demo.mjs:

import assert from 'node:assert/strict';
import { Commerce } from '@stateset/embedded';

const commerce = new Commerce(':memory:');
const customer = await commerce.customers.create({
  email: 'ada@example.com', firstName: 'Ada', lastName: 'Lovelace',
});
const order = await commerce.orders.createExact({
  customerId: customer.id,
  currency: 'USD',
  items: [{ sku: 'MUG-001', name: 'Ceramic mug', quantity: 2, unitPrice: '12.50' }],
});

const paymentInput = {
  orderId: order.id,
  customerId: customer.id,
  amount: order.totalAmountExact,
  currency: 'USD',
  paymentMethod: 'credit_card',
  idempotencyKey: `payment-${order.id}-1`,
};
const payment = await commerce.payments.createExact(paymentInput);
assert.equal(payment.status, 'pending');
assert.equal(payment.amountExact, '25.00');
const paymentReplay = await commerce.payments.createExact(paymentInput);
assert.equal(paymentReplay.id, payment.id);
assert.equal(await commerce.payments.count(), 1);
console.log(`Payment: ${payment.status}, ${payment.amountExact} ${payment.currency}`);
console.log('Payment replay returned the same ID; payment count is 1');

await assert.rejects(
  () => commerce.payments.createRefundExact({
    paymentId: payment.id, amount: '12.50', idempotencyKey: `early-${payment.id}`,
  }),
  { code: 'VALIDATION', message: /Cannot refund a payment in status 'pending'/ },
);
console.log('Refund before payment completion rejected');

// Local simulation: in an integration, first verify the provider's successful result.
const completed = await commerce.payments.markCompleted(payment.id);
assert.equal(completed.status, 'completed');
console.log(`Payment after simulated success: ${completed.status}`);

const refundInput = {
  paymentId: payment.id,
  amount: '12.50',
  reason: 'One mug returned',
  idempotencyKey: `refund-${payment.id}-1`,
};
const refund = await commerce.payments.createRefundExact(refundInput);
assert.equal(refund.status, 'pending');
assert.equal(refund.amountExact, '12.50');
const refundReplay = await commerce.payments.createRefundExact(refundInput);
assert.equal(refundReplay.id, refund.id);
console.log(`Refund: ${refund.status}, ${refund.amountExact}`);
console.log('Refund replay returned the same ID');

await assert.rejects(
  () => commerce.payments.createRefundExact({
    ...refundInput, amount: '20.00', idempotencyKey: `too-large-${payment.id}`,
  }),
  { code: 'VALIDATION', message: /exceeds the refundable balance/ },
);
console.log('Additional 20.00 refund rejected; pending refund uses the balance');

const storedPayment = await commerce.payments.get(payment.id);
const storedOrder = await commerce.orders.get(order.id);
assert.equal(storedPayment.status, 'completed');
assert.equal(storedOrder.paymentStatus, 'paid');
console.log(`Order payment status: ${storedOrder.paymentStatus}`);

// Local simulation: a real integration verifies the provider outcome first.
const settled = await commerce.payments.completeRefund(refund.id);
assert.equal(settled.status, 'completed');
assert.equal((await commerce.payments.get(payment.id)).status, 'partially_refunded');
console.log('Refund after simulated provider acceptance: completed');

node payments-demo.mjs

Success: all assertions pass and you see:

Payment: pending, 25.00 USD
Payment replay returned the same ID; payment count is 1
Refund before payment completion rejected
Payment after simulated success: completed
Refund: pending, 12.50
Refund replay returned the same ID
Additional 20.00 refund rejected; pending refund uses the balance
Order payment status: paid
Refund after simulated provider acceptance: completed

Read the results correctly

Observation	What it establishes
Payment replay returns the same ID	Repeating this request with its original key reuses the local payment record
Refund against the pending payment fails	A newly created payment is not yet refundable
`markCompleted` returns `completed`	The local payment’s state changed; no provider call occurred
Refund replay returns the same ID	Repeating this refund request with its original key reuses the local refund record
Another 20.00 USD refund fails	The pending 12.50 USD refund already counts against the 25.00 USD payment’s refundable balance
Linked order has `paymentStatus: 'paid'`	Completing the full linked payment updates the native order; provider settlement remains separate

Use decimal strings with createExact and createRefundExact, and read amountExact. The binding also exposes numeric money fields; do not convert exact values to JavaScript floating-point numbers for financial calculations.

Integrate with a provider

Keep the local payment ID, provider transaction ID, and your operation’s stable retry key in your integration’s persisted records. A local idempotencyKey does not configure the provider’s own retry behavior. Use that provider’s contract when sending or reconciling a charge or refund. If a provider request times out, its result is unknown. Reconcile the original operation before creating another payment or refund. For local retries, preserve both the original request and its key; generating a new key creates a different operation identity. Only mark a local payment completed after verifying the provider result in a real integration. Update and reconcile order, payment, refund, and inventory state explicitly rather than treating one successful method call as completion of the whole workflow.

The 1.39 binding exposes completeRefund and failRefund. Completion settles the native refund amount into the payment; failure releases its pending reserved capacity. Neither method calls a provider. Record the actual provider result before applying either outcome.

Troubleshooting

Symptom	Check or next step
Refund rejected while payment is pending	Verify the provider outcome before recording payment completion
Refund exceeds the balance	Include pending refunds when evaluating the remaining amount
Multiple records after a retry	Check that the original key and payload were reused in the same database
Order payment state differs from the expected result	Check linked payment identity, amount and actual transitions; reconcile external provider evidence
No provider transaction exists	Expected here: these are local engine calls
Records disappear after exit	`:memory:` is temporary; use a persistent database for integration work

Next steps

Orders quickstart: verify reservation and cancellation behavior.
Returns quickstart: create and receive a return using an actual order item ID.
Durable workflows: explore orchestration across service boundaries.
Finance and accounting: find the broader accounting domains.

Overview

Quickstarts

End-to-end

Commerce Workflows

Order Management

Returns & Warranties

Supply Chain

Agent Development

Knowledge & RAG

Response Features

Advanced Features

Integrations

Commerce Network

Self-Hosted

Best Practices

E-commerce Workflows

Payments & Refunds Quickstart

Prerequisites

Run the complete example

Read the results correctly

Integrate with a provider

Troubleshooting

Next steps

​Prerequisites

​Run the complete example

​Read the results correctly

​Integrate with a provider

​Troubleshooting

​Next steps

Prerequisites

Run the complete example

Read the results correctly

Integrate with a provider

Troubleshooting

Next steps