Custom Plugin
How Feemaker plugins receive payments — no extra infrastructure required.
Step 1: Register a Session Key
Each plugin authenticates as your merchant owner address by signing requests
with a short-lived session key you registered ahead of time. Generate a
fresh EVM private key, keep it inside the plugin, and bind its public half via
POST /auth/register-pubkey. All
subsequent calls send two headers:
| Header | Value |
|---|---|
x-session-nonce | Strictly-increasing integer (millisecond timestamp works) |
x-session-signature | EIP-191 signature over sess:{nonce}:{sha256(body)} |
See Authentication for full signing snippets.
Step 2: Create an Invoice
For each new order, ask Feemaker for an invoice. The server allocates a
deterministic deposit address tied to your owner and returns a hosted
paymentUrl:
POST https://api.feemaker.io/invoice
{
"value": "10",
"chainId": 1,
"description": "Order 123",
"acceptedTokens": ["1:0xdac17f958d2ee523a2206206994597c13d831ec7"],
"deadlineSecs": 86400
}
| Field | Description |
|---|---|
value | Amount in vsCurrency (USD by default). "0" accepts any deposit (tip-jar mode). |
chainId | Deposit chain id (1 Ethereum, 11155111 Sepolia, 728126428 TRON, 56 BSC, …). |
description | Free-form copy displayed on checkout — typically the order id. |
acceptedTokens | Whitelist of "{chainId}:{tokenAddress}" entries. Native coin uses the zero address. |
deadlineSecs | Validity window from creation. Defaults to 90 hours. |
Response includes both the guid (store it against your order) and
paymentUrl. Full schema in POST /invoice.
Step 3: Redirect to Checkout
Send the customer to the paymentUrl returned in Step 2:
https://app.feemaker.io/?invoice=29f3b386-7c4a-4f6e-9d2b-1a8e3c5f7d09
The hosted checkout reads the invoice, shows the deposit address + amount in the chosen token, and the customer pays directly from their wallet. No payment UI work on your side.
Step 4: Listen for Payment Events
Drain invoice-state-change events from the queue with
POST /poll/events. The empty-body request is
authenticated by the same session signature, so no public webhook gateway is
required:
POST https://api.feemaker.io/poll/events
The response is a list of full Invoice records as they were at each state
change. Match guid back to your order and react when status flips to
paid. Recommended cadence is 2–5 seconds for active checkout pages.
Prefer push? Configure a webhook with
POST /auth/register-callback to receive the
same events on your own URL.
Plugin Configuration
When configuring any Feemaker plugin, you will need:
| Parameter | Description |
|---|---|
ownerAddress | Your EVM address that will receive payments |
sessionPrivateKey | Session key registered against ownerAddress (used to sign API calls) |
chainId | The blockchain chain id for your network |
acceptedTokens | List of "{chainId}:{tokenAddress}" entries the plugin will accept |
These replace the traditional API Key / IPN secret approach — Feemaker works directly with the blockchain, so there are no third-party API keys to manage.
Don't see your platform listed? Contact us at support@feemaker.io and we will build a custom plugin tailored to your platform.