Data Types Reference - Modulus Labs API

Overview

This reference documents all shared data types used across both HTTP and WebSocket Terminal Gateway APIs.

PaymentRequest

The payment request object used to initiate payments.

string

Unique transaction identifier in UUIDv7 format. Use this to track and reconcile payments. Auto-generated if not provided.Example: "01945f3d-a8c9-7000-8d45-6f8234ab9012"

string | number

required

Payment amount. Can be a string (recommended for precision) or number.Example: "99.99" or 99.99

string

required

ISO 4217 currency code.Example: "USD", "EUR", "PHP"

string

required

Payment method type.Values: CARD, CASH, MOBILE, OTHER

Product[]

Array of products in the transaction.

CustomerInfo

Customer information for the transaction.

object

Custom key-value pairs for your use. This data is stored with the transaction and returned in responses.Example:

{
  "orderId": "ORD-12345",
  "tableNumber": "T-5",
  "serverName": "John"
}

Example

{
  "transactionId": "01945f3d-a8c9-7000-8d45-6f8234ab9012",
  "amount": "99.99",
  "currency": "USD",
  "paymentMethod": "CARD",
  "products": [
    {
      "id": "PROD-001",
      "name": "Widget",
      "price": "99.99",
      "quantity": 1
    }
  ],
  "customerInfo": {
    "customerId": "CUST-123",
    "email": "customer@example.com"
  },
  "metadata": {
    "orderId": "ORD-12345"
  }
}

PaymentResponse

The payment response object returned when a payment completes.

string

required

Transaction identifier matching your original request.

string

required

Payment status.Values: SUCCESS, FAILED, PENDING, CANCELLED

string | number

required

Payment amount.

string

required

Currency code.

string

required

Payment method used.

string

Authorization code from payment processor. Present on successful payments.Example: "AUTH123456"

string

Error code if status is FAILED.Example: "INSUFFICIENT_FUNDS"

string

Human-readable error message if status is FAILED.Example: "Card declined due to insufficient funds"

string

Opaque receipt data from terminal. Format depends on the terminal’s payment processor.

string

required

ISO 8601 timestamp of when the payment was processed.

object

Your custom metadata returned from the original request.

Successful Payment Example

{
  "transactionId": "01945f3d-a8c9-7000-8d45-6f8234ab9012",
  "status": "SUCCESS",
  "amount": "99.99",
  "currency": "USD",
  "paymentMethod": "CARD",
  "authorizationCode": "AUTH123456",
  "receiptData": "...",
  "timestamp": "2024-01-15T10:37:30.000Z",
  "metadata": {
    "orderId": "ORD-12345"
  }
}

Failed Payment Example

{
  "transactionId": "01945f3d-b2e1-7000-9c67-8a4321cd5678",
  "status": "FAILED",
  "amount": "99.99",
  "currency": "USD",
  "paymentMethod": "CARD",
  "errorCode": "INSUFFICIENT_FUNDS",
  "errorMessage": "Card declined due to insufficient funds",
  "timestamp": "2024-01-15T10:38:00.000Z",
  "metadata": {
    "orderId": "ORD-12346"
  }
}

Product

Product item in a payment request.

string

required

Product identifier.Example: "PROD-001"

string

required

Product name.Example: "Widget"

string | number

required

Unit price.Example: "29.99"

number

required

Quantity purchased.Example: 2

string

Product category.Example: "Electronics"

string

Stock keeping unit.Example: "WDG-001-BLK"

string

Brand name.Example: "Acme Corp"

number

Tax amount for this item.Example: 2.99

number

Discount amount for this item.Example: 5.00

Example

{
  "id": "PROD-001",
  "name": "Widget",
  "price": "29.99",
  "quantity": 2,
  "category": "Electronics",
  "sku": "WDG-001-BLK",
  "brand": "Acme Corp",
  "tax": 5.99,
  "discount": 0
}

CustomerInfo

Customer information for a payment.

string

Customer identifier in your system.Example: "CUST-123"

string

Customer email address.Example: "customer@example.com"

string

Customer phone number.Example: "+1-555-123-4567"

Example

{
  "customerId": "CUST-123",
  "email": "customer@example.com",
  "phone": "+1-555-123-4567"
}

TerminalInfo

Terminal information returned when listing or querying terminals.

string

required

Unique connection identifier. Changes when terminal reconnects.

string

required

Primary identifier. Uses deviceId if available, otherwise connectionId.

string

Stable device identifier. Configured via X-Device-Id header on terminal connection. Persists across reconnections.

string

required

ISO 8601 timestamp of when the terminal connected.

string

required

ISO 8601 timestamp of the terminal’s last activity.

string

required

Terminal status.Values: online, offline, reconnecting

object

Custom terminal metadata.

Example

{
  "connectionId": "abc123xyz",
  "terminalId": "TERM-001",
  "deviceId": "TERM-001",
  "connectedAt": "2024-01-15T10:30:00.000Z",
  "lastActivity": "2024-01-15T10:35:00.000Z",
  "status": "online",
  "metadata": {}
}

TransactionRecord

Transaction record returned when querying transaction status (HTTP API).

string

required

Unique transaction identifier.

string

required

Transaction status.Values: PENDING, COMPLETED, FAILED, CANCELLED, AWAITING_RECONNECT, VOIDED

PaymentRequest

required

Original payment request.

PaymentResponse

Payment response (if completed).

string

required

ISO 8601 timestamp of creation.

string

required

ISO 8601 timestamp of last update.

string

ISO 8601 timestamp of completion (if applicable).

string

Stable terminal device identifier (if available).

string

ISO 8601 timestamp when payment was voided (if applicable).

string

Reason for voiding the payment (if voided).

string

required

ISO 8601 timestamp of this response.

Example

{
  "transactionId": "01945f3d-a8c9-7000-8d45-6f8234ab9012",
  "status": "COMPLETED",
  "request": {
    "transactionId": "01945f3d-a8c9-7000-8d45-6f8234ab9012",
    "amount": "99.99",
    "currency": "USD",
    "paymentMethod": "CARD"
  },
  "response": {
    "transactionId": "01945f3d-a8c9-7000-8d45-6f8234ab9012",
    "status": "SUCCESS",
    "amount": "99.99",
    "currency": "USD",
    "paymentMethod": "CARD",
    "authorizationCode": "AUTH123456",
    "timestamp": "2024-01-15T10:37:30.000Z"
  },
  "createdAt": "2024-01-15T10:37:00.000Z",
  "updatedAt": "2024-01-15T10:37:30.000Z",
  "completedAt": "2024-01-15T10:37:30.000Z",
  "timestamp": "2024-01-15T10:40:00.000Z"
}

VoidResult

The result returned when a void operation is performed.

boolean

required

Whether the void operation succeeded.

string

required

The transaction that was voided.

string

required

Reason for the void.Example: "Terminal reconnected after grace period"

string

ISO 8601 timestamp of when the payment was voided.Example: "2024-01-15T10:38:30.000Z"

string

Error message if the void operation failed.Example: "Transaction already voided"

Example

{
  "success": true,
  "transactionId": "01945f3d-a8c9-7000-8d45-6f8234ab9012",
  "reason": "Terminal reconnected after grace period",
  "voidedAt": "2024-01-15T10:38:30.000Z"
}

Metadata Field

The metadata field allows you to attach custom data to payments. This data is stored with the transaction and returned in responses.

Use Cases

Use Case	Example
Order tracking	Link payments to your order management system
Staff attribution	Track which employee processed the transaction
Custom reporting	Add fields needed for your business reporting
Integration IDs	Store references to external systems

{
  "metadata": {
    "orderId": "ORD-12345",
    "tableNumber": "T-5",
    "serverName": "John",
    "loyaltyPoints": 150
  }
}

The metadata field accepts any valid JSON object. Keys and values should be strings, numbers, or booleans for best compatibility.

Payment Status Definitions

Transaction Status

Status	Description
`PENDING`	Transaction created, awaiting terminal response
`COMPLETED`	Transaction completed successfully
`FAILED`	Transaction failed (see error details)
`CANCELLED`	Transaction was cancelled
`AWAITING_RECONNECT`	Terminal disconnected mid-payment, waiting for reconnection (60-second grace period)
`VOIDED`	Payment was voided (e.g., terminal reconnected after grace period with successful payment)

Payment Response Status

Status	Description
`SUCCESS`	Payment was successfully processed and approved. The `authorizationCode` will be present.
`FAILED`	Payment was declined or encountered an error. Check `errorCode` and `errorMessage` for details.
`PENDING`	Payment is still being processed. This may occur with network issues or terminal communication delays.
`CANCELLED`	Payment was cancelled by the user or terminal operator before completion.

HTTP Error Reference

Error Response Format

All HTTP API errors follow this format:

{
  "error": {
    "code": "TERMINAL_NOT_FOUND",
    "message": "Terminal not found or offline. Please check terminal status and try again.",
    "details": {}
  },
  "timestamp": "2024-01-15T10:40:00.000Z",
  "requestId": "req-abc123"
}

Error Codes

Code	HTTP Status	Description	Recommended Action
`INVALID_REQUEST`	400	Request body is malformed or missing required fields	Check request format and required fields
`INVALID_AMOUNT`	400	Amount is invalid or doesn’t match products total	Verify amount calculation
`UNAUTHORIZED`	401	Missing or invalid API key	Check API key configuration
`INVALID_SIGNATURE`	401	HMAC signature verification failed	Verify signature computation
`TIMESTAMP_EXPIRED`	401	Request timestamp outside 5-minute window	Ensure system clock is synchronized
`GROUP_MISMATCH`	403	Resource belongs to a different group	Verify you’re using the correct API key
`TERMINAL_NOT_FOUND`	404	Specified terminal does not exist	Refresh terminal list
`TRANSACTION_NOT_FOUND`	404	Specified transaction does not exist	Verify transaction ID
`PAYMENT_IN_PROGRESS`	409	Another payment is being processed	Wait for current payment to complete
`RATE_LIMITED`	429	Too many requests	Reduce request frequency
`TERMINAL_CONNECTION_ERROR`	502	Failed to communicate with terminal	Terminal may have disconnected; retry
`TERMINAL_OFFLINE`	503	Terminal is offline or unresponsive	Check terminal connectivity
`TIMEOUT`	504	Terminal did not respond within 90 seconds	Check transaction status endpoint
`INTERNAL_ERROR`	500	Unexpected server error	Contact support if persistent

WebSocket Error Reference

Error Message Format

WebSocket errors follow this format:

{
  "error": "Bad Request",
  "message": "terminalId is required"
}

Common Errors

Error	Message	Cause
Bad Request	Invalid JSON in message body	Malformed JSON in request
Bad Request	terminalId is required	Missing required field
Bad Request	paymentRequest is required	Missing payment data
Not Found	Connection not found	Invalid connection ID
Not Found	Terminal connection not found	Terminal not connected
Forbidden	Only desktop devices can request terminal list	Wrong device type
Forbidden	Cannot send message to connection in different group	Group mismatch
Internal Server Error	Failed to process message	Server-side error

forceDisconnect Reasons

Reason	Description
`api_key_used_elsewhere`	Another device connected with the same API key
`stale_connection_timeout`	Connection was inactive for too long
`admin_action`	Connection terminated by administrator
`server_restarting`	Server is restarting for maintenance or deployment
`other`	Other system-initiated disconnect

Currency Codes

The API uses ISO 4217 three-letter currency codes:

Code	Currency
`USD`	US Dollar
`EUR`	Euro
`GBP`	British Pound
`PHP`	Philippine Peso
`JPY`	Japanese Yen
`CAD`	Canadian Dollar
`AUD`	Australian Dollar

Contact support@moduluslabs.io for the complete list of supported currencies for your integration.

System Constants

Important timeouts and limits to consider when integrating with Terminal Gateway.

Constant	Value	Description
Reconnect grace period	60 seconds	Time allowed for a terminal to reconnect during a mid-payment disconnect
Long poll timeout	90 seconds	Maximum wait time for HTTP API payment requests
Transaction retention (WebSocket)	7 days	How long WebSocket transactions are retained
Transaction retention (HTTP)	30 days	How long HTTP transactions are retained

If a terminal disconnects mid-payment, the system waits up to 60 seconds for reconnection. If the terminal reconnects with a successful payment after this grace period, the payment is automatically voided.

WebhookEndpoint

Configuration object for a webhook endpoint.

string

required

Unique identifier for the webhook endpoint.Example: "wh_01HQ3K4M5N6P7R8S9T0UVWXYZ"

string

required

The HTTPS URL where webhook payloads are delivered.Example: "https://api.yourcompany.com/webhooks/payments"

string[]

required

Event types this endpoint is subscribed to.Values: payment.completed, payment.failed, payment.cancelled, payment.timeout

string

Human-readable description for this endpoint.Example: "Production payment notifications"

string

Webhook signing secret for verifying payloads. Only returned on endpoint creation.Example: "whsec_abc123xyz789..."

string

required

Endpoint status.Values: active, disabled

object

Custom key-value pairs associated with this endpoint.

string

required

ISO 8601 timestamp of when the endpoint was created.

string

required

ISO 8601 timestamp of the last update.

Example

{
  "endpointId": "wh_01HQ3K4M5N6P7R8S9T0UVWXYZ",
  "url": "https://api.yourcompany.com/webhooks/payments",
  "events": ["payment.completed", "payment.failed", "payment.cancelled", "payment.timeout"],
  "description": "Production payment notifications",
  "status": "active",
  "metadata": {
    "environment": "production"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

WebhookPayload

Payload delivered to your webhook endpoint when a payment event occurs.

string

required

The type of event that triggered this webhook.Values: payment.completed, payment.failed, payment.cancelled, payment.timeout

string

required

Unique identifier for this event. Use for idempotency checks.Example: "evt_01HQ3K4M5N6P7R8S9T0UVWXYZ"

string

required

ISO 8601 timestamp of when the event occurred.

object

required

Event-specific payload data containing the payment result.

Show Data fields

string

required

Transaction identifier from the original payment request.

string

required

Payment status: SUCCESS, FAILED, CANCELLED, or TIMEOUT.

string

required

Payment amount.

string

required

ISO 4217 currency code.

string

required

Payment method used.

string

Authorization code from payment processor (success only).

string

Error code if payment failed.

string

Human-readable error message if payment failed.

string

Opaque receipt data from terminal.

string

required

Terminal that processed the payment.

object

Custom metadata from the original payment request.

Example

{
  "eventType": "payment.completed",
  "eventId": "evt_01HQ3K4M5N6P7R8S9T0UVWXYZ",
  "timestamp": "2024-01-15T10:37:30.000Z",
  "data": {
    "transactionId": "TXN-20240115-001",
    "status": "SUCCESS",
    "amount": "99.99",
    "currency": "USD",
    "paymentMethod": "CARD",
    "authorizationCode": "AUTH123456",
    "receiptData": "...",
    "terminalId": "TERM-001",
    "metadata": {
      "orderId": "ORD-12345"
    }
  }
}

WebhookEventType

Event types that can trigger webhook notifications.

Event Type	Description	Trigger
`payment.completed`	Payment succeeded	Terminal returns `SUCCESS` status
`payment.failed`	Payment declined or error	Terminal returns `FAILED` status
`payment.cancelled`	User cancelled payment	Terminal returns `CANCELLED` status
`payment.timeout`	Terminal didn’t respond	90-second timeout reached

Payment Methods

Supported payment method values:

Method	Description
`CARD`	Credit or debit card payment
`CASH`	Cash payment
`MOBILE`	Mobile payment (e.g., Apple Pay, Google Pay)
`OTHER`	Other payment method

Timestamps

All timestamps in the API use ISO 8601 format with UTC timezone:

2024-01-15T10:30:00.000Z

Parsing Timestamps

const timestamp = message.timestamp;
const date = new Date(timestamp);

console.log(date.toLocaleDateString()); // Local date
console.log(date.toLocaleTimeString()); // Local time

from datetime import datetime

timestamp = message['timestamp']
date = datetime.fromisoformat(timestamp.replace('Z', '+00:00'))

print(date.strftime('%Y-%m-%d %H:%M:%S'))  # Formatted date/time

Next Steps

Authentication

Learn about API authentication methods

Core Concepts

Understand device enforcement and reconnection resilience

HTTP Endpoints

Complete HTTP endpoint reference

WebSocket Actions

WebSocket commands reference

​Overview

​PaymentRequest

​Example

​PaymentResponse

​Successful Payment Example

​Failed Payment Example

​Product

​Example

​CustomerInfo

​Example

​TerminalInfo

​Example

​TransactionRecord

​Example

​VoidResult

​Example

​Metadata Field

​Use Cases

​Payment Status Definitions

​Transaction Status

​Payment Response Status

​HTTP Error Reference

​Error Response Format

​Error Codes

​WebSocket Error Reference

​Error Message Format

​Common Errors

​forceDisconnect Reasons

​Currency Codes

​System Constants

​WebhookEndpoint

​Example

​WebhookPayload

​Example

​WebhookEventType

​Payment Methods

​Timestamps

​Parsing Timestamps

​Next Steps

Authentication

Core Concepts

HTTP Endpoints

WebSocket Actions

Overview

PaymentRequest

Example

PaymentResponse

Successful Payment Example

Failed Payment Example

Product

Example

CustomerInfo

Example

TerminalInfo

Example

TransactionRecord

Example

VoidResult

Example

Metadata Field

Use Cases

Payment Status Definitions

Transaction Status

Payment Response Status

HTTP Error Reference

Error Response Format

Error Codes

WebSocket Error Reference

Error Message Format

Common Errors

forceDisconnect Reasons

Currency Codes

System Constants

WebhookEndpoint

Example

WebhookPayload

Example

WebhookEventType

Payment Methods

Timestamps

Parsing Timestamps

Next Steps