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.

transactionId

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"

amount

string | number

required

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

currency

string

required

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

paymentMethod

string

required

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

products

Product[]

Array of products in the transaction.

customerInfo

CustomerInfo

Customer information for the transaction.

metadata

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.

transactionId

string

required

Transaction identifier matching your original request.

status

string

required

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

amount

string | number

required

Payment amount.

currency

string

required

Currency code.

paymentMethod

string

required

Payment method used.

authorizationCode

string

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

errorCode

string

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

errorMessage

string

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

receiptData

string

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

timestamp

string

required

ISO 8601 timestamp of when the payment was processed.

metadata

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"

name

string

required

Product name.Example: "Widget"

price

string | number

required

Unit price.Example: "29.99"

quantity

number

required

Quantity purchased.Example: 2

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.

customerId

string

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

string

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

phone

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.

connectionId

string

required

Unique connection identifier. Changes when terminal reconnects.

terminalId

string

required

Primary identifier. Uses deviceId if available, otherwise connectionId.

deviceId

string

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

connectedAt

string

required

ISO 8601 timestamp of when the terminal connected.

lastActivity

string

required

ISO 8601 timestamp of the terminal’s last activity.

status

string

required

Terminal status.Values: online, offline, reconnecting

metadata

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).

transactionId

string

required

Unique transaction identifier.

status

string

required

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

request

PaymentRequest

required

Original payment request.

response

PaymentResponse

Payment response (if completed).

createdAt

string

required

ISO 8601 timestamp of creation.

updatedAt

string

required

ISO 8601 timestamp of last update.

completedAt

string

ISO 8601 timestamp of completion (if applicable).

terminalDeviceId

string

Stable terminal device identifier (if available).

voidedAt

string

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

voidReason

string

Reason for voiding the payment (if voided).

timestamp

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.

success

boolean

required

Whether the void operation succeeded.

transactionId

string

required

The transaction that was voided.

reason

string

required

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

voidedAt

string

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

error

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.

endpointId

string

required

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

url

string

required

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

events

string[]

required

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

description

string

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

secret

string

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

status

string

required

Endpoint status.Values: active, disabled

metadata

object

Custom key-value pairs associated with this endpoint.

createdAt

string

required

ISO 8601 timestamp of when the endpoint was created.

updatedAt

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.

eventType

string

required

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

eventId

string

required

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

timestamp

string

required

ISO 8601 timestamp of when the event occurred.

data

object

required

Event-specific payload data containing the payment result.

Show Data fields

transactionId

string

required

Transaction identifier from the original payment request.

status

string

required

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

amount

string

required

Payment amount.

currency

string

required

ISO 4217 currency code.

paymentMethod

string

required

Payment method used.

authorizationCode

string

Authorization code from payment processor (success only).

errorCode

string

Error code if payment failed.

errorMessage

string

Human-readable error message if payment failed.

receiptData

string

Opaque receipt data from terminal.

terminalId

string

required

Terminal that processed the payment.

metadata

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

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

QR API

Onboarding API

Terminal Gateway

Shared Resources

​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