Asynchronous Integration via Webhooks

The Getnet C2C API supports an asynchronous operational mode designed for decoupled systems that require high responsiveness. In this mode, your software receives an immediate acknowledgment that the command was sent, while the final transaction result is pushed to a specified listener URL once the process completes.

Enabling Asynchronous Mode

Include the optional webhook parameter in the JSON request body to transition an endpoint from synchronous to asynchronous behavior.
  • Trigger: The presence of a valid URL in the webhook field automatically switches the API to asynchronous mode.
  • Instant Acknowledgment: The API immediately returns a code: 1 response with the message "TRANSACTION SENT".
  • Correlation ID: This initial response includes an idPosTxs (Unique Transaction ID). Your system must store this ID to correlate the incoming webhook callback with the original merchant request.

Webhook Callback Flow

Once the physical POS terminal finishes the operation—whether approved, rejected, or timed out—the Getnet Cloud initiates a POST request to your provided URL.

Callback Characteristics

  • Method: POST.
  • Payload: A full JSON object representing the terminal state of the transaction, identical in structure to a standard synchronous response.
  • Security: The merchant is responsible for ensuring the listener endpoint is secure and operationally available.

Testing and Verification

For initial development and debugging, Getnet recommends using third-party inspection tools to validate the callback payload before deploying your production listener.

Verifying with Webhook site

  1. Generate a unique, temporary URL at webhook site.
  2. Copy the "Your unique URL" value.
  3. Include this URL in the webhook field of your transactional request.
  4. Execute the request and monitor the Webhook site dashboard. The final transaction metadata will appear in the "Raw Content" section once the POS interaction is complete.

Operational Best Practices

Adhere to the following guidelines for a robust asynchronous implementation:

  • Endpoint Security: Use unique endpoints or include a security token in your URL query string (e.g., https://api.merchant.com/callback?token=XYZ) to authorize incoming requests.
  • Immediate Acknowledgment: Your listener should return an HTTP 200 OK promptly upon receiving the payload to signal successful delivery to the Getnet Cloud.
  • Polling Fallback: If a webhook is not received within the expected timeframe, use the Status Query endpoint as a secondary verification method.
  • Firewall Whitelisting: If your infrastructure restricts incoming traffic, you must request the official Getnet Cloud egress IP addresses from technical support.

Next Steps

After implementing webhooks, ensure you have robust handling for transaction states and timeouts:

On this page

Asynchronous Integration via Webhooks