@olares/payment-sdk

Olares Payment is a payment gateway for merchants. After you get API keys in the Dashboard, you can create payments, send buyers to the hosted checkout, and fulfill orders once the onchain settlement completes.

This package is the gateway's official TypeScript client for Node.js servers. Requests are signed with HMAC. Keep the API secret out of browsers and other untrusted runtimes.

Requirements

• Node.js 18 or later
• Merchant API key (pk_) and secret (sk_)
• Webhook secret (whsec_), optional. The Dashboard issues it when you register a webhook endpoint.

The SDK points at the production gateway https://www.olares.com/payment by default. Override baseUrl for a test environment or a self-hosted deployment.

Installation

npm install @olares/payment-sdk

Usage

Create a MerchantClient. The receive account is bound to the key pair, so you do not pass it in requests.

import { MerchantClient } from '@olares/payment-sdk';

const client = new MerchantClient({
  apiKey: process.env.PAYMENT_API_KEY!,
  apiSecret: process.env.PAYMENT_API_SECRET!,
});

Create a payment

createPayment returns a hosted checkout URL. Send the buyer to checkoutUrl to complete the payment.

const { paymentId, checkoutUrl } = await client.createPayment({
  amountCents: 1999,
  returnUrl: 'https://merchant.example/orders/ord_123',
});

amountCents is the price in cents: 1999 means $19.99. returnUrl is where the buyer returns after payment and can be omitted.

Confirm a payment

Check paid from getPayment, or register a webhook and fulfill on payment.succeeded.

const result = await client.getPayment(paymentId);
if (result.paid) {
  const { txHash } = result.credential;
}

import { webhooks } from '@olares/payment-sdk';

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const event = webhooks.constructEvent(req, process.env.PAYMENT_WEBHOOK_SECRET!);
  if (event.type === 'payment.succeeded') {
    // event.paymentId, event.credential.txHash
  }
  res.status(200).send('ok');
});

The webhook body must be the raw bytes. In Express, use express.raw, not express.json.

Links

• Documentation: https://www.olares.com/docs/developer/payment/
• API reference: https://www.olares.com/docs/developer/payment/api-reference/
• Olares product site: https://olares.com

License

AGPL-3.0-or-later. See LICENSE.