@m2c/server

Server-side Node / TypeScript SDK for the M2C payment-vendor auction API.

It keeps the security-sensitive parts off your plate:

• createAuction(...) - run an auction and get the winning vendor's hosted checkout URL.
• handleConversionWebhook(...) - verify and dispatch the signed conversion webhook M2C delivers when a payment's status changes, in one call.
• verifyConversionWebhook(...) - the lower-level verify-and-parse primitive the handler wraps, for when you want to own the dispatch and response yourself.

This is the secret-key SDK. Your secret key must never ship in a browser or mobile app; for client-side auctions use a publishable key and the mobile / web SDKs.

Requires Node 18+ (uses the built-in fetch and node:crypto).

Install

npm install @m2c/[email protected]

Quick start

Version 0.11.0 requires refund responses containing requested_at and must_confirm_by. Deploy the updated bid server and retire older serving revisions before upgrading. See CHANGELOG.md.

import { M2CClient } from '@m2c/server';

const m2c = new M2CClient({
  secretKey: process.env.M2C_SECRET_KEY!,
});

const auction = await m2c.createAuction({
  transactionValue: 49.99, // major units of currency
  currency: 'USD',
  customerIp: req.ip,      // the END USER's IP - see "Calling on behalf of a device"
  reference: order.id,     // echoed back in the conversion webhook
  successUrl: 'https://store.example.com/thanks',
  cancelUrl: 'https://store.example.com/cart',
  description: '100 Gems',
}, { idempotencyKey: order.checkoutKey }); // persist once per checkout attempt

// Send auction.winner.checkoutUrl to the client to open. Persist auction.requestId
// against your order so you can correlate the conversion webhook later.

order is loaded from your authenticated application's database. Persist the price, request parameters and checkout key before the first call and reuse them unchanged on retries, including customer metadata. The examples below use application-owned fulfillment helpers; the SDK verifies and dispatches events but does not store orders or make fulfillment idempotent for you.

Configuration

new M2CClient(options) accepts:

| Option | Type | Default | Notes | |---|---|---|---| | secretKey | string | (required) | Your sec_... key. Server-side only. | | baseUrl | string | https://api.m2cmarkets.com | The production API host is baked in; you normally leave this unset. Override only to point at a mock or non-production endpoint when testing. A trailing slash is trimmed. | | timeoutMs | number | 10000 | Per-request timeout. On expiry the call throws M2CApiError with code: 'unavailable' and status: 0. | | fetch | typeof fetch | global fetch | Override for testing or a custom HTTP stack. Requires Node 18+ otherwise. |

Calling on behalf of a device

When your backend runs the auction for a mobile or web client, the connection IP M2C sees is your server's, not the user's. Secret keys derive geo from the customerIp you pass, so forward the real device IP:

await m2c.createAuction({ transactionValue: 9.99, customerIp: endUserIp });

You can also attach optional checkout-context metadata on createAuction: platform (web | webgl | ios | android | desktop) and deviceType. Both are recorded on the auction, forwarded to bidding vendors, and echoed back on the conversion webhook as event.platform / event.deviceType. Metadata only - never auth or fulfillment. (The client SDKs, @m2c/checkout and the Unity SDK, auto-detect and send these; on the server you pass whatever your request context knows.)

Fulfillment: act on the webhook, not the redirect

The customer being redirected back to your successUrl is a UX event, not proof of payment - it can be dropped or spoofed. Grant value only when you receive a verified completed conversion webhook. Correlate via requestId (or your reference).

handleConversionWebhook verifies the signature over the raw body and dispatches the verified event to your onEvent callback, returning the status + body to write back:

import { handleConversionWebhook } from '@m2c/server';

// Express example. You MUST verify against the RAW body bytes - capture them
// before any JSON parser rewrites them (see "Capturing the raw body"):
//   app.post('/webhooks/m2c', express.raw({ type: '*/*' }), handler)
async function handler(req, res) {
  const { status, body } = await handleConversionWebhook({
    secret: process.env.M2C_WEBHOOK_SECRET!,
    rawBody: req.body,    // raw Buffer / string, NOT a parsed object
    headers: req.headers,
    onEvent: async (event) => {
      // Sandbox conversions arrive at this same URL with the signed test flag
      // set - never fulfill real goods for them.
      if (event.test) return;
      // Your application helper must correlate the saved order and commit
      // event identity, sequence and fulfillment/reversal in one transaction.
      // Await the commit; throw on failure so delivery can retry.
      await applyConversionInTransaction(event);
    },
  });
  res.status(status).send(body); // 204 on success, 400 on a bad/missing signature
}

The handler returns 400 (and does NOT call onEvent) on a bad or missing signature, and 204 after onEvent resolves. An empty secret is local configuration failure and still throws. Throw from onEvent to signal a transient failure: the throw propagates, so your route returns 5xx and M2C retries with backoff, then dead-letters.

Capturing the raw body

The signature covers timestamp + "\n" + rawBody. A re-serialized JSON object will not reproduce the exact signed bytes (key order, whitespace), so passing a parsed object always fails verification - hand the verifier the original request body. How you keep the raw bytes depends on your framework:

• Express: mount the raw parser on this route before any JSON parser:

  app.post('/webhooks/m2c', express.raw({ type: '*/*', limit: '64kb' }), async (req, res, next) => {
    try {
      const result = await handleConversionWebhook({ rawBody: req.body, headers: req.headers, /* ... */ });
      res.status(result.status).send(result.body);
    } catch (err) {
      next(err);
    }
  });

• Fastify: register a buffer parser for the webhook content type:

  fastify.addContentTypeParser(
    'application/json',
    { parseAs: 'buffer' },
    (_req, body, done) => done(null, body),
  );
  fastify.post('/webhooks/m2c', async (req, reply) => {
    const result = await handleConversionWebhook({ rawBody: req.body as Buffer, headers: req.headers, /* ... */ });
    return reply.code(result.status).send(result.body);
  });

• Next.js route handler: read await req.text() or Buffer.from(await req.arrayBuffer()); do not call await req.json() first.

• Node http: concatenate the request stream into a Buffer yourself and pass that.

rawBody accepts a string or Buffer; headers accepts Node's IncomingHttpHeaders or a WHATWG Headers.

Lower-level: verifyConversionWebhook

When you want to own the dispatch and the response yourself, call the primitive the handler wraps. It verifies and parses, throwing M2CSignatureError on an untrusted delivery and plain M2CError on an authentic-but-off-contract payload:

import { verifyConversionWebhook, M2CSignatureError } from '@m2c/server';

let event;
try {
  event = verifyConversionWebhook(process.env.M2C_WEBHOOK_SECRET!, req.body, req.headers);
} catch (err) {
  if (err instanceof M2CSignatureError) {
    return res.status(400).json({ error: 'invalid signature' }); // untrusted - do not act
  }
  throw err;
}
// ... branch on event.test / event.status, then res.status(204).end()

Requesting a refund

Ask M2C to start a refund for a completed conversion. M2C relays a signed request to the winning vendor, which executes it at its PSP and confirms back on the conversion webhook (status: 'refunded') - that webhook, not this call, is the authoritative refund signal. You may request multiple partial refunds until their cumulative value reaches the original refundable total.

const refund = await m2c.requestRefund(requestId, {
  amount: 9.99, // major units in the conversion's currency; > 0 and <= the original total
  reason: 'requested_by_customer', // optional reason code, relayed to the vendor
  idempotencyKey: 'refund-order-1234', // required; a retry with the same key replays the same request
});
// refund.refundRequestId - correlate with the eventual webhook
// refund.status - 'pending' on first accept, or the existing status on an idempotent replay
// refund.requestedAt - original request timestamp, unchanged on replay
// refund.mustConfirmBy - fixed deadline, or null for unknown historical deadlines

Requires a secret key (a publishable key is rejected). The amount is shape-checked locally; the refundable total is enforced server-side. Failures throw M2CApiError with a stable code (see Error handling): 404 (not_found - conversion not found or not yours, distinct from the auction's no_winner), 409 (conflict - idempotency-key mismatch, not refundable, or the vendor has no refund endpoint), 422 (unprocessable - refund window expired or billing period archived), and 400 (bad_request - missing/invalid idempotency key or invalid amount). None are retryable.

Error handling

Invalid input (e.g. transactionValue out of range) throws M2CError before any network round-trip. All SDK errors extend M2CError, so a single catch (err) { if (err instanceof M2CError) ... } covers everything.

createAuction throws M2CApiError (a subclass) on a non-2xx response or a network/timeout failure, with a stable code so you can branch without matching message strings:

| code | HTTP | Meaning | |---|---|---| | bad_request | 400 | Invalid parameters. | | unauthorized | 401 | Missing or invalid key. | | forbidden | 403 | Origin/redirect not allowed, or account suspended. | | no_eligible_vendors | 404 | No eligible vendor is linked. Check account configuration. | | no_bids / no_valid_bids | 404 | No usable checkout was returned. Offer a customer-visible retry or another payment method. | | no_winner | 404 | Auction 404 without a more specific code. | | not_found | 404 | requestRefund only: the conversion doesn't exist or isn't yours. (The auction route uses no_winner for 404.) | | auction_in_progress | 409 | Retry the same key and body after Retry-After. | | idempotency_mismatch | 422 | Same key, different body. Fix the caller; do not blindly switch keys. | | conflict / unprocessable | 409 / 422 | Other conflicts or policy limits, including refund state/window restrictions. | | rate_limited | 429 | Slow down; see error.retryAfterSeconds. | | server_error | 500 (or other non-gateway 5xx) | Internal error; may be a transient fault. | | unavailable | 502/503/504, or 0 | Transient: gateway error, cold start, or a network/timeout failure with no HTTP response (status is 0). See error.retryAfterSeconds. |

error.retryable is true for auction_in_progress, 429, any 5xx, and network/timeout failures.

For retryable errors, preserve both key and body, honor retryAfterSeconds, and use bounded exponential backoff with jitter (for example at most three attempts, waiting at least 1, 2, then 4 seconds). After that, keep the order pending for reconciliation. Never silently create a new checkout or switch vendors after a timeout: the first attempt may have succeeded. Successful auction results are replayable for 24 hours; do not blindly retry after that window or reopen an expired checkout URL.

createAuction does not retry internally - it surfaces the M2CApiError with retryable set and leaves the decision to you. Without an idempotencyKey, a retry starts a fresh, separately billed auction, so only retry bare calls when running a new auction is acceptable. Pass an idempotencyKey (as below) and a retry replays the original auction's outcome instead. This is deliberately different from @m2c/vendor's reportConversion, which owns its bounded transient retry behavior. Conversion reports remain idempotent on request_id for initial outcomes or reversalId for refunds and chargebacks.

import { randomUUID } from 'node:crypto';
import { M2CApiError } from '@m2c/server';

// One key per logical checkout, reused across retries: the server replays the
// original auction outcome instead of running a fresh, separately billed
// auction with a potentially different winner.
const idempotencyKey = randomUUID();
try {
  await m2c.createAuction({ transactionValue: 49.99 }, { idempotencyKey });
} catch (err) {
  if (err instanceof M2CApiError && ['no_winner', 'no_eligible_vendors', 'no_bids', 'no_valid_bids'].includes(err.code)) {
    // No vendor available - show an alternative path, don't treat as a crash.
  } else if (err instanceof M2CApiError && err.retryable) {
    // back off and retry with the SAME idempotencyKey
  } else {
    throw err;
  }
}

verifyConversionWebhook throws M2CSignatureError with a reason (missing | incomplete | malformed | timestamp_skew | mismatch | empty_secret). A malformed-but-present signature is a tampering signal, kept distinct from a fully-absent one.

If the signature verifies but the payload doesn't match the conversion contract (bad JSON, unknown status, value/reversal rule violation), it throws plain M2CError instead: the delivery is authentic, so treat it as contract drift to investigate, not tampering. Alerting on M2CSignatureError alone will therefore never page on benign contract evolution.

handleConversionWebhook folds the first case into a 400 response for you and lets the second (the authentic-but-off-contract M2CError) propagate, so it surfaces as a 5xx you can alert on rather than a silent 204.

Reference: data shapes

The SDK presents all fields in camelCase; the API's snake_case wire format is mapped for you in both directions.

createAuction(params) returns AuctionResult:

| Field | Type | Notes | |---|---|---| | winner.vendorId | string | Winning vendor's id. | | winner.checkoutUrl | string | Hosted checkout URL to open. Time-boxed by ttl. | | winner.ttl | number | Seconds the checkout URL stays valid. | | clearingRate | number | Winning fee rate as a percentage (e.g. 2.9 = 2.9%). | | feeProceeds | number | Fee charged on the transaction, in the auction currency. | | bidCount | number | Number of valid bids received. | | requestId | string | Correlate with the conversion webhook. | | latencyMs | number | Auction latency in milliseconds. |

verifyConversionWebhook(...) returns a verified ConversionEvent:

| Field | Type | Notes | |---|---|---| | event | 'conversion' | Event-type discriminator. | | requestId | string | Matches the auction's requestId. Primary correlation key. | | status | ConversionStatus | completed | failed | abandoned | refunded | chargedback. | | vendor | string | Winning vendor's id. | | transactionId | string | Vendor's transaction id (may be empty). | | timestamp | string | RFC 3339 UTC emit time. Distinct from the signing-timestamp header. | | deliveryId | string? | Present when a delivery ledger row exists; stable across retries. | | eventSequence | number? | Monotonic per-auction transition order on current live deliveries. Compare and advance it in the same transaction as fulfillment or reversal state. Absent on sandbox and legacy queued deliveries. | | reference | string? | Your auction reference, echoed back when set. | | platform | string? | Checkout surface attached from the auction row when known. Metadata only; do not gate fulfillment on it. | | deviceType | string? | Coarse device form factor attached from the auction row when present. Metadata only. | | sessionId | string? | Shop-session identifier for a session purchase or its reversal. Use with purchaseId for fulfillment correlation. | | purchaseId | string? | Vendor-supplied idempotent purchase identifier for a session purchase or its reversal. | | value | number? | Converted amount in the original auction currency, when applicable. | | reversalId | string? | Stable identifier for this refund or chargeback event. | | reversalValue | number? | Incremental reversed amount in the original auction currency. | | cumulativeReversalValue | number? | Total reversed after this event. | | remainingRefundableValue | number? | Amount still available for later reversals. |

requestRefund(requestId, params) takes RequestRefundParams and returns RefundRequestResult:

| Field | Type | Notes | |---|---|---| | amount (param) | number | Refund amount in major units. > 0 and <= the refundable total. | | reason (param) | string? | Optional reason code: requested_by_customer, duplicate, fraudulent, not_received, or other. Any other value returns 400. | | idempotencyKey (param) | string | Required 1-255 printable-ASCII key; the same key replays the same request. | | refundRequestId (result) | string | M2C's id for the request; correlate it with the eventual refunded webhook. | | status (result) | string | pending | sent | confirmed | failed | rejected. failed means delivery is uncertain; rejected means delivery was definitively not accepted, including when no vendor target was available. Advisory; the webhook is authoritative. | | cumulativeReversalValue (result) | number | Total value already reversed. | | remainingRefundableValue (result) | number | Unreserved value still available for another refund request. | | requestedAt (result) | string | Original request timestamp; unchanged on idempotent replay. | | mustConfirmBy (result) | string \| null | Fixed confirmation deadline, capped by the original reversal cutoff. null preserves an unknown historical deadline. |

An elapsed deadline or a failed relay is not proof of nonexecution. The request can remain reserved while the vendor outcome is uncertain. Keep its stable refundRequestId for reconciliation; the signed conversion webhook remains the authority for a completed refund.

Money is represented in decimal major units at this SDK's surface (for example, dollars for USD or euros for EUR).