Merchant SDK

UI-free helpers for merchant-side EthosPay integration.

The recommended entry point is createMerchantApiClient. It wraps the main backend APIs as business-level methods, so integration code can pass params and receive useful result objects without manually building RPC envelopes.

For checkout flows, these fields should be documented from the payment middle-page perspective, not the raw backend request shape. The page needs enough information to create a usable payment order, and it can auto-generate a local user_id or order number if the host app does not provide one.

Recommended Usage

import { createMerchantApiClient } from '@ethospay/payment-sdk';

const client = createMerchantApiClient({
  apiBaseUrl: 'https://dev.ethospay.top/basicapi',
  merchantId: '[email protected]',
  signRequest: async ({ requestBody, requestUrl }) => {
    // Recommended: call your own backend to sign the request.
    // Do not put the merchant private key in browser code.
    const response = await fetch('/api/ethospay/sign', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ requestBody, requestUrl }),
    });

    return response.json();
  },
});

signRequest should call a merchant-controlled backend signing endpoint. The browser should not hold the merchant private key.

Main APIs

| SDK method | Backend method | Purpose | Returns | | --- | --- | --- | --- | | client.newUser(params) | new_user | Create a pay-in order/address. | AgentflowNewUserData | | client.getChainConfigs() | get_chain_configs | Load supported chains and tokens. | AgentflowChainConfig[] | | client.getOrderInfo(order) | get_order_infor | Load hosted payment order details. | AgentflowOrderInfo | | client.queryPayinTransaction(params) | query_payin_transaction | Query a wallet transaction confirmation. | AgentflowQueryPayinTransactionData |

The client throws Error(message) when the backend returns a non-200 code or missing data.

Create a pay-in order

const payin = await client.newUser({
  chain: 'bsc_testnet',
  user_id: 'ORDER-10001',
  merchant_name: 'Demo Merchant',
  token_symbol: 'USDT',
  token_addr: '0x4BC18724CFCee6a147172EfA437CE97682c7B998',
  expected_amount: '20.00',
});

window.location.href = payin.payment_web_url || '';

Important result fields from backend:

| Field | Description | | --- | --- | | chain | Chain used by the order. | | user_id | Merchant-side user/order identifier. | | address | Receiving address. | | expire_at | Expiration timestamp. | | is_first | Whether this is a first binding/allocation result. | | invoice_id | Optional invoice ID. | | merchant_order_id | Optional merchant order ID. | | status | Optional order status. | | payment_web_url | Hosted payment URL returned by the backend. |

Checkout note: from the middle-page perspective, chain, token selection, and expected_amount are required. user_id is the order number; if the host app does not provide one, the page may generate it before calling new_user. merchant_name, token_addr, expire_seconds, and remark are optional page inputs.

Load chain config

const chains = await client.getChainConfigs();
const bsc = chains.find((chain) => chain.chain === 'bsc_testnet');
const tokens = bsc?.tokens || [];

Each chain may include chain, name, symbol, rest_url, rpc_url, payout_contract, and tokens. Each token may include name, symbol, contract_addr, and decimal.

Load hosted payment order details

const orderInfo = await client.getOrderInfo(orderFromUrl);

if (isMissingOrderInfo(orderInfo)) {
  throw new Error('Payment order not found');
}

Important result fields include merchant_id, merchant_name, user_id, chain, token_symbol, token_addr, address, expected_amount, received_amount, status, expire_at, tx_hash, from_address, confirmed_at, and order_found.

Query transaction status

const tx = await client.queryPayinTransaction({
  chain: 'bsc_testnet',
  tx_hash: '0x...',
  user_id: 'ORDER-10001',
});

if (tx.confirmed && tx.receipt) {
  console.log(tx.receipt.amount, tx.receipt.confirmed_at);
}

The backend returns status, confirmed, and optional receipt. A pending or unmatched transaction returns confirmed: false with no receipt.

Hosted Payment Page Helpers

For payment middle pages that already have a hosted order token, these helpers convert and validate order data for the payment UI:

import {
  fetchHostedPaymentOrderInfo,
  isMissingOrderInfo,
  isPaidOrderStatus,
  toEthosPayInitialPayment,
  toEthosPayInvoicePayload,
} from '@ethospay/payment-sdk';

const { orderInfo } = await fetchHostedPaymentOrderInfo(
  'https://dev.ethospay.top/basicapi',
  orderFromUrl
);

const initialPayment = toEthosPayInitialPayment(orderInfo);
const invoicePayload = toEthosPayInvoicePayload(orderInfo);
const paid = isPaidOrderStatus(orderInfo.status);

React Payment UI Adapter

Use createPaymentAdapter only when embedding @ethospay/payment-ui directly. It keeps the old payment UI props shape: requestUrl, signedRequest, and queryInvoice.

import { createPaymentAdapter } from '@ethospay/payment-sdk';

const adapter = createPaymentAdapter({
  apiBaseUrl: 'https://dev.ethospay.top/basicapi',
  merchantId: '[email protected]',
  signRequest: async ({ requestBody, requestUrl }) => {
    const response = await fetch('/api/ethospay/sign', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ requestBody, requestUrl }),
    });

    return response.json();
  },
});

Low-Level Helpers

Request builders are still exported for tests, demos, and advanced integrations, but they are not the recommended starting point for most frontend developers.

import {
  createGetChainConfigsRequest,
  createNewUserRequest,
  createGetOrderInfoRequest,
  createQueryPayinTransactionRequest,
} from '@ethospay/payment-sdk';

createGetChainConfigsRequest();
createNewUserRequest({ chain: 'bsc_testnet', user_id: 'ORDER-10001' });
createGetOrderInfoRequest('encoded-order-token');
createQueryPayinTransactionRequest({ chain: 'bsc_testnet', tx_hash: '0x...' });

withPublicOrderId is kept as an advanced request mutation helper. Most integrations should pass the merchant's public order identifier through user_id when calling client.newUser(params).