MQ Behavior in Sandbox & Production

Use Newline’s Message Queue (MQ) to consume pull-based, durable event notifications in Sandbox and Production.

The Sandbox MQ environment mirrors the Production architecture and protocols, but event timing and data realism may differ during testing.

How MQ Delivery Works

The following delivery mechanics apply in both Sandbox and Production.

MQ is pull-based, not push-based.

• Connect to the MQ broker and consume messages from subscribed topics.
• Use durable subscriptions:
  • Messages are retained when a client disconnects.
  • Clients can resume consumption after reconnecting.

MQ is built on Apache ActiveMQ and AWS MQ.

Polling & Consumption Expectations (Sandbox)

The following expectations describe how events may be generated when you test in Sandbox. Do not interpret them as Production timing or delivery guarantees.

In Sandbox, clients should expect:

Non‑Immediate Delivery

Events may not appear immediately after an action is performed.

Variable Timing

Some events are generated synchronously, while others are published asynchronously.

Empty Polls

Polling a topic may return no messages if no qualifying events have occurred.

MQ does not guarantee real-time delivery. Do not use Sandbox timing to infer Production sequencing or SLAs.

Best practice: Design consumers to tolerate delays, retries, and intermittent empty reads in all environments.

Sandbox vs Production MQ Endpoints

MQ endpoints are environment-specific. Connect to the endpoint for the environment you are testing.

Sandbox and Production use separate brokers and credentials. Sandbox connections do not interact with or reflect Production traffic or behavior.

Sandbox Endpoints

• AMQP: amqp+ssl://mq-sandbox.newline53.com:5671
• STOMP: stomp+ssl://mq-sandbox.newline53.com:61614
• MQTT: mqtt+ssl://mq-sandbox.newline53.com:8883
• WSS: wss://mq-sandbox.newline53.com:61619

Connection Requirements

All connections must:

• Use SSL/TLS
• Authenticate using credentials provided during onboarding
• Include required protocol-specific headers, such as client-id and subscriptionName for STOMP

Sandbox credentials are not valid for Production endpoints.

Topics & Event Types in Sandbox

The following information applies when you consume MQ events in Sandbox.

Sandbox publishes events using the same topic categories and schemas as Production, but event presence, timing, and frequency may differ. Do not treat Sandbox events as representative of Production.

RTP Queue Testing

The Sandbox environment supports RTP queue testing scenarios that allow clients to validate queue lifecycle behavior and event handling.

flowchart TD
    A[Created] --> B[Queued]
    B --> C[Settled]
    B --> D[Failed]

Successful Queue Processing

To test a successful queue workflow, initiate an Instant Payment transfer using the following memo value:

queue_then_settle

Expected Behavior

flowchart LR
    A[Transfer Initiated] --> B["Memo: queue_then_settle"]
    B --> C[Queued]
    C --> D["queued_until populated"]
    D --> E[Settled]

During testing:

• A transfer_queued event is published.
• The transfer enters Queued status.
• The queued_until field is populated.
• The transfer transitions to Settled before the queued_until timestamp expires.

Failed Queue Processing

To test a failed queue workflow, initiate an Instant Payment transfer using the following memo value:

queue_then_fail

Expected Behavior

flowchart LR
    A[Transfer Initiated] --> B["Memo: queue_then_fail"]
    B --> C[Queued]
    C --> D["queued_until populated"]
    D --> E[Failed]

During testing:

• A transfer_queued event is published.
• The transfer enters Queued status.
• The queued_until field is populated.
• After the queued_until timestamp has elapsed, the transfer transitions to Failed.

queued_until Behavior

The queued_until field indicates the expected time at which queue processing should complete.

In Sandbox testing scenarios, queued_until is typically populated with a timestamp approximately three minutes after transfer initiation.

Topic Naming Convention

MQ topics follow this format:

/topic/<client>.<environment>.<topic_name>

Example

/topic/neal.abc-enterprises.sandbox.transfer

• <client>: Your organization or integration name
• <environment>: sandbox or production
• <topic_name>: The entity or event category (e.g., transfer, transaction)

Event Payloads

Event payloads are delivered in JSON format and include:

• event_type
• details object
• Unique event_id

Certain queue-related events may additionally include:

• queued_until
• status

Sandbox Event Realism & Limitations

While schema and topic structure match Production:

• Events may be synthetic or generated specifically to exercise workflows.
• Certain real‑world dependencies (such as bank posting or settlement timing) may not be fully represented.
• Event order and timing observed in Sandbox may differ from Production and should not be relied on.
• Queue-processing scenarios may be simulated using supported memo values such as queue_then_settle and queue_then_fail.
• Do not interpret Sandbox queue timing as representative of Production processing timelines.

FAQs

“I triggered an action but don’t see an event yet.”

MQ delivery may be asynchronous. Retry polling and confirm your subscription is active.

“I received the same message twice.”

Use event_id to deduplicate. Durable subscriptions may re-deliver messages after reconnects.

“No messages are coming through.”
Confirm the following:

• Correct Sandbox endpoint
• Correct topic name
• Durable subscription configuration
• Authentication headers

"What is transfer_queued?"

transfer_queued indicates that a transfer has entered queue processing and has not yet reached a final outcome.

"What is queued_until?"

queued_until indicates when queue processing is expected to complete.

Queued transfers may subsequently settle or fail.

Best Practices for Sandbox MQ Testing

• Test using durable subscriptions.
• Implement retry logic and idempotency.
• Validate behavior across disconnect and reconnect scenarios.
• Test in Sandbox before enabling MQ in Production.
• Validate handling of transfer_queued events.
• Validate both successful and failed queue-processing scenarios.
• Continue monitoring queued transfers until you receive a final transfer outcome.