Server SDKs

About the Server SDKs

The Server SDK is the primary interface for interacting with Composer. It calls checkpoints at key moments of risk in your application and helps you interpret the responses.

Every server SDK has the same methods and behavior, with names that follow each language's conventions. The examples on this page use Node.js. Your SDK's README has the same examples in your language. The few places where the SDKs behave differently are listed in Differences between SDKs.

Prerequisites

You will need to obtain a secret API key for your application from the Dodgeball developer center. For setup instructions, see your SDK’s README in Available SDKs. If you don't already have an account, contact support.

Related

Server SDKs work alongside the JavaScript Client SDK, which runs in the browser and supplies the source token each checkpoint uses.

Migrating an existing integration? See From Dodgeball or From Composer (legacy). If you're upgrading from a Dodgeball server SDK, also see Changes from the Dodgeball server SDKs.

For runnable reference apps, see composer-examples. It includes a server example in every supported language and a Next.js client example that uses the JavaScript Client SDK.

Available SDKs

Installation

Use npm to install the Node.js SDK:

npm install @spreedly/composer-sdk-server

Alternatively, using yarn:

yarn add @spreedly/composer-sdk-server

Configuration

Initialize the SDK with your secret API key.

import { Composer } from '@spreedly/composer-sdk-server';

const composer = new Composer(process.env.SPREEDLY_SECRET_KEY, {
  apiUrl: 'https://api.sandbox.dodgeballhq.com',
  logLevel: 'ERROR',
  requestTimeoutMs: 5000
});

Every SDK has these options with the same defaults, named to follow each language’s conventions. See your SDK’s README for the exact names.

Usage

At a moment of risk, such as placing an order, call a checkpoint and act on the result:

import { Composer } from '@spreedly/composer-sdk-server';
import express from 'express';
import { isIP } from 'net';

const app = express();
app.use(express.json());

const composer = new Composer(process.env.SPREEDLY_SECRET_KEY);

// Client IP for the risk engine. Callers must not choose this value.
// Default (TRUSTED_PROXY_COUNT=0): socket address, ignore X-Forwarded-For.
// Positive count: that many hops from the right of X-Forwarded-For; the hop must be an IP.
// Set TRUSTED_PROXY_COUNT only if your app runs behind trusted reverse proxies.
const getIp = (req) => {
  const hops = Number(process.env.TRUSTED_PROXY_COUNT ?? '0');
  if (!Number.isInteger(hops) || hops < 0) {
    throw new Error('Cannot derive client IP: TRUSTED_PROXY_COUNT is not a valid hop count');
  }

  const header = req.headers['x-forwarded-for'];
  const parts = (Array.isArray(header) ? header.join(',') : (header ?? '')).split(',').map((part) => part.trim());
  const candidate =
    hops === 0 ? req.socket.remoteAddress : hops <= parts.length ? parts[parts.length - hops] : undefined;
  if (!candidate || !isIP(candidate)) {
    throw new Error('Cannot derive client IP: no valid IP for this TRUSTED_PROXY_COUNT');
  }
  return candidate;
};

app.post('/api/orders', async (req, res) => {
  // In moments of risk, call a checkpoint within Composer to verify the request is allowed to proceed
  const checkpointResponse = await composer.checkpoint({
    checkpointName: 'PLACE_ORDER',
    event: {
      ip: getIp(req),
      data: {
        order: req.body.order
      }
    },
    sourceToken: req.headers['x-dodgeball-source-token'], // Obtained from the JavaScript Client SDK, represents the device making the request
    sessionId: req.session.id, // Assumes session middleware such as express-session
    userId: req.session.userId,
    useVerificationId: req.headers['x-dodgeball-verification-id'] // See Handling Additional Verification
  });

  if (composer.isAllowed(checkpointResponse)) {
    // Proceed with placing the order
    const placedOrder = await database.createOrder(req.body.order);
    return res.status(200).json({
      order: placedOrder
    });
  } else if (composer.isRunning(checkpointResponse)) {
    // The checkpoint needs input from the user. See Handling Additional Verification
    return res.status(202).json({
      verification: checkpointResponse.verification
    });
  } else if (composer.isDenied(checkpointResponse)) {
    // If the request is denied, you can return the verification to the frontend to display a reason message
    return res.status(403).json({
      verification: checkpointResponse.verification
    });
  } else {
    // The checkpoint failed or finished without a decision. Decide how you would like to proceed: return the error, proceed, retry, or reject the request.
    return res.status(500).json({
      message: checkpointResponse.errors
    });
  }
});

app.listen(process.env.APP_PORT, () => {
  console.log(`Listening on port ${process.env.APP_PORT}`);
});

Checkpoint Parameters

checkpoint() throws if a required parameter is missing (Go returns the error instead). Network failures and timeouts never throw: they come back as a failed response, with success false and an error code of 500. getIp throws when it can’t derive a valid IP, rather than substituting a guess.

Interpreting the Checkpoint Response

Every checkpoint call creates a verification. Use the helper methods to decide what to do, rather than reading status and outcome directly.

Verification Statuses

Verification Outcomes

Possible Responses and Helper Methods

Each helper takes the checkpoint response, for example composer.isAllowed(checkpointResponse).

When the polling time set by options.timeout runs out, the verification is still pending, not timed out: isRunning() returns true, and you can resume later with useVerificationId.

Handling Additional Verification

When a checkpoint needs input from the user, such as MFA or a 3DS challenge, isRunning returns true:

1. Return the verification to your frontend.
2. Pass it to the JavaScript Client SDK's handleVerification(), which prompts the user.
3. When the user completes the step, your frontend retries the request with the verification ID, and your server passes it to useVerificationId.

Each verification ID can only be used once, to prevent replay attacks.

Processing Spreedly Transactions

A checkpoint's workflow can run Spreedly transaction steps such as authorization, capture, and purchase. Transaction details go in event.data.

1. Tokenize the payment method first. Collect and vault the payment method with a Spreedly tokenization method, then send the resulting payment method token to your server.
2. Find the fields your checkpoint expects. In the checkpoint, open the Trigger node, then Expected Data > Copy Schema as JSON. The schema has the same shape as event.data and lists every field your workflow's steps need that no earlier step provides.
3. Send those fields in the checkpoint call:

const checkpointResponse = await composer.checkpoint({
  checkpointName: 'PAYMENT',
  event: {
    ip: getIp(req),
    data: {
      // The exact fields depend on your workflow. Use your checkpoint's Expected Data schema.
      paymentMethod: { token: req.body.paymentMethodToken },
      transaction: { amount: 1000, currency: 'USD' } // amount is an integer in minor units: 1000 = $10.00
    }
  },
  sourceToken: req.headers['x-dodgeball-source-token'],
  sessionId: req.session.id
});

Handle the response the same way as in Usage. A 3DS challenge follows Handling Additional Verification. The Client SDK doesn't take payment fields, and you don't need to add Spreedly.ThreeDS separately.

To test, set each transaction step's Gateway Token to a Spreedly test gateway. If a step's Gateway Token is blank, the step uses transaction.gatewayToken from event.data instead.

Differences between SDKs

The SDKs behave the same except for the following:

• Missing required parameters in Go: Checkpoint returns a ComposerMissingParameterError as its error value instead of throwing. The other SDKs throw.
• Request timeout in Python and Ruby: the request timeout applies to each stage of a request (connecting, then waiting for data), not to the whole request, because their HTTP libraries have no single overall deadline. A slow response can take longer than request_timeout_ms in total. The other SDKs cap the whole request.
• Empty objects in PHP: the SDK decodes responses as PHP arrays, so an empty object in verification->stepData arrives as []. When you send data, use a stdClass (or (object) []) for an object, because json_encode sends an empty array, or one keyed 0, 1, 2…, as a JSON list.

Changes from the Dodgeball server SDKs

If you're upgrading from a Dodgeball server SDK, your SDK's changelog lists everything that changed, including renamed packages and classes and new default behavior. Read its Changed and Removed sections for the steps to migrate.