Quickstart

const crypto = require('crypto');

const API_KEY = process.env.MODULUS_API_KEY;
const API_SECRET = process.env.MODULUS_API_SECRET;
// The gateway prefix belongs in the URL you call, but NOT in the path you sign.
const BASE_URL = 'https://api.sbx.moduluslabs.io/v1/terminal-gateway';

/**
 * Generate authentication headers for HTTP API requests.
 * `path` is the endpoint path to sign (e.g. /v1/terminals), without the gateway prefix.
 */
function generateAuthHeaders(method, path, body = null) {
  const timestamp = new Date().toISOString();

  // SHA256 hash of body (empty string for GET)
  const bodyString = body ? JSON.stringify(body) : '';
  const bodyHash = crypto
    .createHash('sha256')
    .update(bodyString)
    .digest('hex');

  // Construct string to sign
  const stringToSign = `${method}\n${path}\n${timestamp}\n${bodyHash}`;

  // Compute HMAC-SHA256 signature
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(stringToSign)
    .digest('base64');

  return {
    'Content-Type': 'application/json',
    'x-api-key': API_KEY,
    'x-timestamp': timestamp,
    'x-signature': signature
  };
}

/**
 * Step 1: Get available terminals
 */
async function getTerminals() {
  const path = '/v1/terminals';
  const headers = generateAuthHeaders('GET', path);

  const response = await fetch(`${BASE_URL}${path}`, {
    method: 'GET',
    headers
  });

  if (!response.ok) {
    throw new Error(`Failed to get terminals: ${response.status}`);
  }

  return response.json();
}

/**
 * Step 2: Initiate a payment
 */
async function createPayment(terminalId, paymentData) {
  const path = `/v1/terminals/${terminalId}/payments`;
  const headers = generateAuthHeaders('POST', path, paymentData);

  const response = await fetch(`${BASE_URL}${path}`, {
    method: 'POST',
    headers,
    body: JSON.stringify(paymentData)
  });

  return response.json();
}

/**
 * Step 3: Check transaction status
 */
async function getTransaction(transactionId) {
  const path = `/v1/transactions/${transactionId}`;
  const headers = generateAuthHeaders('GET', path);

  const response = await fetch(`${BASE_URL}${path}`, {
    method: 'GET',
    headers
  });

  return response.json();
}

// Main flow
async function main() {
  try {
    // 1. Discover terminals
    console.log('Getting terminals...');
    const terminalsResponse = await getTerminals();
    console.log(`Found ${terminalsResponse.count} terminal(s)`);

    if (terminalsResponse.terminals.length === 0) {
      console.log('No terminals available');
      return;
    }

    const terminal = terminalsResponse.terminals[0];
    console.log(`Using terminal: ${terminal.deviceId}`);

    // 2. Initiate payment
    console.log('Initiating payment...');
    const paymentResult = await createPayment(terminal.deviceId, {
      // transactionId is optional; omit it and the gateway generates a UUID v7
      amount: '99.99',
      currency: 'USD',
      paymentMethod: 'CARD',
      products: [
        { id: 'PROD-001', name: 'Widget', price: '99.99', quantity: 1 }
      ],
      metadata: { orderId: 'ORD-12345' }
    });

    console.log('Payment result:', paymentResult.status);

    if (paymentResult.paymentResponse) {
      console.log('Authorization:', paymentResult.paymentResponse.authorizationCode);
    }

    // 3. Optionally check transaction status
    if (paymentResult.transactionId) {
      console.log('Checking transaction status...');
      const txn = await getTransaction(paymentResult.transactionId);
      console.log('Transaction status:', txn.status);
    }

  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

import hashlib
import hmac
import base64
import json
import os
from datetime import datetime, timezone
import requests

API_KEY = os.getenv('MODULUS_API_KEY')
API_SECRET = os.getenv('MODULUS_API_SECRET')
# The gateway prefix belongs in the URL you call, but NOT in the path you sign.
BASE_URL = 'https://api.sbx.moduluslabs.io/v1/terminal-gateway'


def generate_auth_headers(method: str, path: str, body_string: str = '') -> dict:
    """Generate authentication headers for HTTP API requests.

    `path` is the endpoint path to sign (e.g. /v1/terminals), without the gateway prefix.
    `body_string` is the exact JSON string you send ('' for GET).
    """
    timestamp = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%S.000Z')

    # SHA256 hash of the exact body string (empty string for GET)
    body_hash = hashlib.sha256(body_string.encode()).hexdigest()

    # Construct string to sign
    string_to_sign = f'{method}\n{path}\n{timestamp}\n{body_hash}'

    # Compute HMAC-SHA256 signature
    signature = base64.b64encode(
        hmac.new(
            API_SECRET.encode(),
            string_to_sign.encode(),
            hashlib.sha256
        ).digest()
    ).decode()

    return {
        'Content-Type': 'application/json',
        'x-api-key': API_KEY,
        'x-timestamp': timestamp,
        'x-signature': signature
    }


def get_terminals():
    """Step 1: Get available terminals."""
    path = '/v1/terminals'
    headers = generate_auth_headers('GET', path)

    response = requests.get(f'{BASE_URL}{path}', headers=headers)
    response.raise_for_status()

    return response.json()


def create_payment(terminal_id: str, payment_data: dict):
    """Step 2: Initiate a payment."""
    path = f'/v1/terminals/{terminal_id}/payments'

    # Serialize once, sign that string, and send that same string
    body_string = json.dumps(payment_data)
    headers = generate_auth_headers('POST', path, body_string)

    response = requests.post(
        f'{BASE_URL}{path}',
        headers=headers,
        data=body_string
    )

    return response.json()


def get_transaction(transaction_id: str):
    """Step 3: Check transaction status."""
    path = f'/v1/transactions/{transaction_id}'
    headers = generate_auth_headers('GET', path)

    response = requests.get(f'{BASE_URL}{path}', headers=headers)

    return response.json()


def main():
    try:
        # 1. Discover terminals
        print('Getting terminals...')
        terminals_response = get_terminals()
        print(f"Found {terminals_response['count']} terminal(s)")

        if not terminals_response['terminals']:
            print('No terminals available')
            return

        terminal = terminals_response['terminals'][0]
        print(f"Using terminal: {terminal['deviceId']}")

        # 2. Initiate payment
        print('Initiating payment...')
        payment_result = create_payment(terminal['deviceId'], {
            # transactionId is optional; omit it and the gateway generates a UUID v7
            'amount': '99.99',
            'currency': 'USD',
            'paymentMethod': 'CARD',
            'products': [
                {'id': 'PROD-001', 'name': 'Widget', 'price': '99.99', 'quantity': 1}
            ],
            'metadata': {'orderId': 'ORD-12345'}
        })

        print(f"Payment result: {payment_result.get('status')}")

        if payment_result.get('paymentResponse'):
            print(f"Authorization: {payment_result['paymentResponse'].get('authorizationCode')}")

        # 3. Optionally check transaction status
        if payment_result.get('transactionId'):
            print('Checking transaction status...')
            txn = get_transaction(payment_result['transactionId'])
            print(f"Transaction status: {txn['status']}")

    except Exception as e:
        print(f'Error: {e}')


if __name__ == '__main__':
    main()