Custom storefront integrations

The SDK preview supports one-time USD orders through USDC on Base checkout. It includes invoice creation, retrieval and cancellation, raw webhook signature verification, and exact payment checks. Your application remains responsible for durable order storage, retries, recovery, and fulfillment. Subscriptions, saved cards, automatic refunds, and bank-transfer checkout are unavailable. Other platforms may have additional payment-provider requirements.

Install on your server

Download the SDK tarball and install it in a Node.js 20 or later application. The package is a local distribution preview and is not published to npm.

npm install ./ulasend-commerce-0.1.0.tgz

Connect your account

1. Use an approved Ulasend merchant account with USDC on Base enabled under accepted coins.
2. Copy your merchant ID from Integrations.
3. In Developers, create a test API key with invoices:write, which also permits invoice reads.
4. Store the key on your server. Use separate credentials and saved orders for test and live mode.

The key determines the client's mode. Keys beginning with pk_test_ or pk_live_ are both secret and must never appear in browser code. The SDK calls the hosted Ulasend API.

Create an invoice

import { createUlasendClient } from '@ulasend/commerce';

const ulasend = createUlasendClient({
  apiKey: process.env.ULASEND_API_KEY,
});

const { order } = await ulasend.createInvoice({
  usdAmount: '25.00',
  orderReference: 'store-123:order-456:attempt-1',
  idempotencyKey: 'store-123:order-456:attempt-1',
  successUrl: 'https://merchant.example/orders/456',
});
// Save order with your platform order before redirecting to order.checkoutUrl.

Read the total from your server's order record. Save a stable payment attempt and lock the order before calling Ulasend. A retry must use the same reference, request body, and idempotency key. Save the returned invoice ID and full quoted amount before redirecting, and keep them immutable. The quote may include a processing fee and conversion rounding above the cart total.

The API's response replay cache lasts 24 hours. If a timeout or lost response leaves you without an invoice ID, stop automatic creation retries before that window ends and retain the attempt for recovery or support review. Do not change the key or assume retries remain safe forever. Resolve the original attempt before creating another checkout.

Set up payment notifications

Create a separate webhook endpoint and signing secret for each mode in Developers. Use a publicly reachable HTTPS receiver and subscribe to invoice events. Save the secret on your server, then select Verify in Ulasend. Live key creation and live endpoint changes require an account owner or administrator with two-factor authentication.

Verify before fulfilling

Use verifyWebhookEvent with the raw body, signature, event ID, signing secret, expected merchant and mode. Preserve the original bytes before JSON parsing. For the authenticated webhook.endpoint_verification event, return HTTP 200 with a JSON challenge field equal to event.data.challenge. This event has no merchant ID and is never payment evidence. For an invoice notification, find the saved order using event.resource_id and call ulasend.verifyPayment(savedOrder)using that order's mode.

Fulfillment requires the full saved quote, even if the account allows small crypto shortfalls. Deduplicate notifications and update the order in a durable transaction. Acknowledge delivery only after durably saving the event or processing result; temporary API or storage failures must remain retryable.

Test and recover orders

Start with a test key and confirm the hosted page shows test mode before simulating payment. The SDK can verify simulated invoices; your application must route them to a test workflow that never fulfills real orders. Test duplicates, lost notifications, partial payments, changed totals, and cancelled orders before configuring separate live credentials.

Schedule reconciliation of unresolved orders with verifyPayment, retaining each attempt's original mode. Pending and partial payments must not release fulfillment, and a missing notification must not create a new invoice. Contact Ulasend if an uncertain attempt cannot be recovered.

The SDK does not send fulfillment emails, change stock, or manage your database. Late payments on cancelled or refunded orders require review, and a return URL never proves payment. Cancelling an invoice does not refund a transfer.

The included README covers setup and recovery. See also the API authentication and webhook integration guides.