Overview

Polling is the process of periodically querying the Status Inquiry endpoint to retrieve the current state of a transaction.

It is primarily used in scenarios where real-time feedback is required or where webhook notifications are not yet available or cannot be relied upon.

When implemented correctly, polling enables responsive user experiences and robust transaction monitoring, while avoiding unnecessary load on the SIBS Payment Gateway.

Polling strategies must be designed in accordance with the transaction state semantics defined in E.2.4 – Status Semantics and Interpretation.

Polling strategies must be designed to complement, and not replace, the event-driven model provided by webhook notifications.

When to Use Polling

Polling should be used in the following scenarios:

• During interactive payment flows, where the user is waiting for confirmation
• When webhook delivery is delayed or uncertain
• As a fallback mechanism in case webhook processing fails
• For short-lived monitoring windows immediately after transaction creation

Polling must not be used as a permanent substitute for webhook-based integrations and must always be complemented by webhook-driven mechanisms.

Polling Principles

The following principles must be respected:

• Polling must be time-bound and not run indefinitely
• Polling frequency must be progressively reduced over time
• Polling must respect API rate limits and throttling policies defined by SIBS. Excessive request rates may result in request throttling, temporary blocking, or degraded service performance.
• Polling must stop when a final transaction state is reached
• Polling must be combined with webhook-based updates
• Polling logic must be implemented in server-side components only
• Polling strategies must be designed to avoid synchronized request patterns across multiple transactions.
• Polling strategies must be designed to degrade gracefully under failure conditions, avoiding cascading retries or amplification of system load.

Recommended Polling Strategy

A staged polling strategy should be implemented to balance responsiveness and system efficiency.

Initial Phase (0-30 seconds)

• Frequency: every 2-3 seconds
• Objective: provide near real-time feedback during active user interaction

Intermediate Phase (30 seconds – 2 minutes)

• Frequency: every 5-10 seconds
• Objective: reduce load while still tracking transaction progress

Extended Phase (> 2 minutes)

• Frequency: exponential backoff (e.g., 15s → 30s → 60s)
• Objective: minimize system impact for long-running transactions

Stop Conditions

Polling must stop immediately when:

• A final transaction state is reached:
  • Success
  • Declined
  • Error
  • Timeout
• A maximum polling duration is exceeded
• The user abandons the flow

Maximum Polling Duration

Polling duration must be limited according to the payment method:

• Card payments: typically a few seconds to ~1 minute
• MB WAY: up to ~4 minutes (user authorization window)
• Multibanco Reference: may require long-term monitoring (handled via webhooks or backoffice, not continuous polling)

Polling beyond reasonable time windows must be avoided.

Handling Transient States

Polling is required while the transaction is in a non-final state:

• Pending
• InProcessing

Guidelines:

• Continue polling according to the defined strategy
• Do not trigger business actions
• Use webhooks to complement status updates

Error Handling During Polling

When polling requests fail:

• Retry requests using the same backoff strategy
• Distinguish between:
  • Transient errors (retryable)
  • Permanent errors (require intervention)

Examples:

• 500 Internal Server Error → retry
• 401 Unauthorized → validate token configuration
• 404 Not Found → validate transactionID

Concurrency and Load Management

To avoid excessive load:

• Do not poll multiple times in parallel for the same transaction
• Avoid polling large batches of transactions simultaneously
• Implement request throttling if necessary

Polling must be designed to scale safely under high transaction volumes.

Polling strategies must avoid coordinated bursts across multiple transactions that could lead to systemic load spikes.

API Rate Limits and Throttling

The SIBS Payment Gateway may enforce rate limiting and throttling mechanisms to protect system stability and ensure fair usage across clients.

Integrators must design polling strategies that:

• Avoid excessive request bursts
• Respect defined request rate limits
• Implement backoff mechanisms in case of throttling responses

In case of throttling, integrators must reduce request frequency and retry after an appropriate delay.

Integrators must assume that rate limits may be enforced dynamically based on system load and must design adaptive polling strategies accordingly.

Integration with Webhooks

Polling must be used in conjunction with webhooks:

• Webhooks provide event-driven updates
• Polling provides state validation and fallback

Best practice:

• Use polling during active flows
• Use webhooks for background updates
• Always validate final state using Status Inquiry

Idempotency Considerations

Status Inquiry requests are idempotent:

• They can be safely repeated
• They do not modify transaction state

This property enables safe retry and polling implementations.

Security Considerations

• Polling must be executed from secure server-side components
• Authentication credentials must not be exposed
• Avoid logging sensitive information in polling loops
• Polling endpoints must never be exposed directly to client-side applications or browser-based execution contexts.

Key Integration Principles

• Use polling only when necessary
• Always combine polling with webhook mechanisms
• Stop polling as soon as a final state is reached
• Implement progressive backoff strategies
• Ensure scalability and controlled load

Summary

Polling is a complementary mechanism to webhook notifications, enabling:

• Real-time transaction monitoring
• Improved user experience during payment flows
• Increased resilience in asynchronous environments

When implemented using controlled frequency, backoff strategies, and proper stop conditions, polling ensures efficient, scalable, and reliable transaction tracking within the SIBS Payment Gateway ecosystem.