Queue Communication

Queue delivery is intended for POS systems that cannot receive inbound OpenApp HTTP calls.

OpenApp owns and manages the queue, an Amazon SQS FIFO queue per location. The POS receives the queue URL, region, and AWS credentials during activation. The credentials can only receive and delete messages.

Queue Behavior

• Ordering. Messages are FIFO within a message group (MessageGroupId), the ordering key chosen by OpenApp. Messages in different groups have no ordering guarantee.
• At-least-once delivery. The POS can receive the same message more than once and must deduplicate by messageId.
• Visibility timeout: 30 seconds. A received message stays hidden from other consumers for 30 seconds. If the POS does not delete it within that time, SQS delivers it again.
• Blocked groups. While a message is received but not deleted, SQS holds back later messages in the same group. Slow processing delays that whole group.
• Retention: 14 days. SQS drops messages that stay in the queue longer.

Queue Message Envelope

The message body is a JSON envelope. messageKind and messageId are also sent as SQS message attributes.

Field	Description
messageKind	Message name used to route and deserialize the message.
apiVersion	API version of the message. Currently v1.
messageId	Unique message ID used for deduplication and callback correlation.
idempotencyKey	Business-level deduplication key. Retries of the same business operation reuse the same value.
payload	Message-specific payload.

For a duplicated command, the POS should return the same business result where possible.

Consuming Messages

1. Call ReceiveMessage with long polling (WaitTimeSeconds: 20), continuously while the integration is active.
2. Skip messages whose messageId the POS has already processed.
3. Process the command.
4. Send the result to the callback endpoint.
5. Call DeleteMessage with the message's ReceiptHandle, based on the callback response:

Callbacks

After processing a message, the POS sends the result, signed with its API credentials, to:

POST /merchant/v1/async/{messageKind}/{messageId}

The body is the result payload for that message kind.

Response	Meaning
204	Result accepted. A repeated callback for an already accepted message also returns 204; OpenApp ignores the repeat.
400	The body is invalid for this message kind. The message stays open.
404	The message does not exist, belongs to another merchant or location, or its kind does not match {messageKind}.

Testing The Round Trip

Use the Test message to verify queue polling, callbacks, and deletion before implementing business messages.

1. Call POST /merchant/v1/async/test, signed with the POS credentials. OpenApp returns { "messageId": "..." }. Credentials from a non-POS integration receive 403.
2. Receive the Test message from the queue. Its payload contains a nonce.
3. Call POST /merchant/v1/async/Test/{messageId} with { "nonce": "<value from the payload>" }. OpenApp returns 204, or 400 if the nonce does not match.
4. Delete the message.

POS-Initiated Events

POS-initiated events should include a unique message identifier so OpenApp can deduplicate repeated delivery.