Service Operation Logic: Sync vs Async

The Getnet Cloud-to-Cloud (C2C) API provides two distinct operational modes for managing transaction lifecycles. The choice between Synchronous and Asynchronous behavior is determined dynamically by the presence or absence of the webhook parameter in the request payload.

Synchronous Operation

In a synchronous flow, the Cashier Software maintains an active HTTP connection while the terminal processes the transaction. This is the default behavior when the webhook parameter is omitted.

Synchronous Operational Workflow

Initiate Request: Send the command (e.g., Sale, Refund) to the API without a webhook parameter.
Maintain Connection: Keep the HTTP connection open while the cloud identifies the target terminal.
Customer Interaction: The POS terminal prompts the user for action (e.g., "Present card").
Final Response: Once the transaction is finalized, the terminal returns the result to the cloud, which then delivers it as the final HTTP response.
Success Confirmation: A successful execution returns code: 1 with the message "TRANSACTION FINISHED".

Important: Connection Persistence: The Cloud API remains open for a maximum of 5 minutes. If the POS exceeds a 90-second response window, the system continues to wait for an additional 3.5 minutes. Ensure your HTTP client is configured to allow long-lived connections.

Asynchronous Operation

The asynchronous mode is designed for decoupled, event-driven architectures where an immediate acknowledgement is preferred. To enable this, include a valid webhook parameter in your request body.

Asynchronous Operational Workflow

Initiate Request: Include the webhook parameter with your unique listener URL.
Immediate Acknowledgment: The API validates the payload and instantly returns code: 1 with the message "TRANSACTION SENT".
Capture ID: Store the idPosTxs returned in the initial response for tracking the transaction state.
Background Execution: The terminal processes the transaction independently of the initial API connection.
Callback: Upon completion, the Getnet Cloud pushes a POST request containing the full transaction outcome to your specified webhook URL.

Comparison and Decision Matrix

Choose the execution mode that best fits your system architecture and user interface requirements.

Feature	Synchronous Mode	Asynchronous Mode
Trigger	Omit the `webhook` parameter.	Provide a valid `webhook` URL.
Initial Response	Final Transaction Result.	`"TRANSACTION SENT"` acknowledgment.
Timeout Window	Up to 5 minutes.	Immediate (milliseconds).
Success String	`"TRANSACTION FINISHED"`	`"TRANSACTION SENT"`
Use Case	Linear workflows and simpler logic.	Event-driven microservices.

Operational Best Practices

Request Tracking: In both modes, store the unique idPosTxs returned by the API. This ID is essential for querying the transaction status manually if a response or webhook is lost.
Secure Webhooks: Maintain a single, secure endpoint for your webhooks. You are responsible for the security, signature validation, and uptime of this listener.
Status Query Fallback: If a response is not received (sync) or a webhook fails to arrive (async), use the Status Query endpoint with the stored idPosTxs to verify the final state on our backend.
Concurrent Operations: Do not attempt a new operation on the same terminal until the previous lifecycle is complete. Retrying too early may return a code: 0 error.