Getnet DocsGetnet Docs

Set up Webhooks and Notifications

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Because interactions with physical terminals take time (e.g., waiting for a PIN entry), the Get Smart API Cloud returns the final result of a transaction asynchronously.

To receive this result, you must expose a public HTTP endpoint (Webhook) on your server. The API Cloud will send a POST request to this URL containing the final transaction details, authorization codes, and receipt data.

Configuration

You define where to send the notification per request. This means you can route different transactions to different endpoints if necessary.

In every API call (Payment, Refund, Pre-authorization), include the notificacion object:

{
  "info": {
    "notificacion": {
      "urlNotificacion": "https://your-server.com/api/webhooks/payments",
      "correoNotificacion": "[email protected]"
    },
    ...
  }
}
  • urlNotificacion: The primary channel. Must be a publicly accessible HTTPS URL.
  • correoNotificacion: The fallback channel. If your server is down or returns an error (non-200), the system will email the result to this address.

The Notification Payload

When the terminal finishes processing, your server will receive a JSON payload.

Method: POST

Content-Type: application/json

Example Payload

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timeStamp": "20250428 111500",
    "datosRespuesta": {
      "tipoPago": "PAGO",
      "importe": "25.50",
      "moneda": "978",
      "factura": "ORD-2025-001",
      "resultado": "Autorizada",
      "codigoRespuesta": "998877",
      "estado": "F",
      "tarjetaClienteRecibo": "************1234",
      "marcaTarjeta": "1",
      "Literales": {
         "autenticadoPorPin": "OPERACION CON PIN. FIRMA NO NECESARIA."
      }
    }
  },
  "signature": "INCOMING_SERVER_SIGNATURE"
}

Key Fields to Process

FieldDescription
resultadoThe human-readable result: Autorizada or Denegada.
codigoRespuestaThe authorization code (if approved) or error code (if denied). Save this for reconciliation.
estadoF (Finalized), A (Cancelled), G (Denied), T (Technical Error).
LiteralesContains mandatory text to be printed on the receipt (e.g., “Verification by PIN”).
datosDCCPresent only if Dynamic Currency Conversion occurred. Contains exchange rate details.
paisTarjetaThe 3-digit ISO-3166 numeric code of the card’s country (e.g., 840 for USA, 724 for Spain). Useful for analytics or fraud logic.

Securing Your Webhook

Because your webhook URL is public, anyone could theoretically send fake requests to it. You must verify the signature of every incoming notification.

Verification Steps

  1. Capture the Raw Body: Read the incoming JSON body.
  2. Extract info: Separate the info object from the signature.
  3. Calculate Hash:
    • Minimize the info JSON string (remove whitespace).
    • Append your merchant key.
    • Calculate SHA256.
  4. Compare: Check if your calculated hash matches the signature in the payload.

Security Warning: If the signatures do not match, discard the request immediately. Do not update your order status or release goods.

Best Practices

1. Idempotency

Network retries might cause you to receive the same notification twice. Ensure your system can handle duplicate requests for the same factura (Invoice ID) without charging the customer twice or corrupting your database.

2. Acknowledge Quickly

Your server should return a 200 OK status immediately after receiving and storing the webhook data. If you take too long to respond, the API Cloud might consider the delivery a failure and trigger the email fallback.

3. Handle Fallbacks

If you receive an email notification (because your server was down), it will contain the same data in a human-readable format. You may need a manual process to update orders based on these emails if your automated system fails.

Troubleshooting

IssuePossible Cause
Signature MismatchYou might be using the wrong environment key (Test vs. Production), or your JSON parser is reordering fields before you calculate the hash.
No Notification ReceivedCheck your firewall settings. Ensure your server accepts connections from the internet on the specified port.
Email Received InsteadYour server returned a 4xx/5xx error or timed out, triggering the fallback mechanism.

Next Steps