Skip to main content

Notification Proactive (confirmation URL)

This document describes the proactive notification (confirmation URL) behaviour: how to request it, what to expect, and how to implement the receiver.

What is a confirmation URL?​

When creating a Remote Payment you can optionally provide a confirmation URL (same as callback_url) and a callback token. If you do, the system will proactively POST to that URL every time the transaction changes state (authorized, refused, cancelled, aborted, refunded, etc.). This allows your system to react in real time (e.g. update POS UI, reconcile payments).

This is a very good alternative compared to issuing repeated queries while waiting for the response.

When notifications are sent​

Typical state changes that produce notifications:

  • Payment pending → approved (confirmed successful on terminal)
  • Payment pending → refused (card denied / terminal refused)
  • Payment → cancelled (manual cancel)
  • Payment → aborted (session aborted)
  • Refund created / Refund updated → notification containing refund details

Important: Not every Sylq internal statuses triggers a callback. Only mutations / state changes (the internal endpoints or app API flows listed below) cause callbacks.

Payload & headers​

Callback POSTs include:

  • Header:
    • Authorization: Bearer <callback_token>
    • Content-Type: application/json
  • Body:
    • For general payment status updates: the JSON representation of the payment resource (see examples below).
    • For refunds events: the JSON representation of the refunds collection payload (see examples below).

Example events (short)​

  • Payment confirmed
    • Event: card_status
    • Body: payment JSON (status: confirmed)
  • Payment refused
    • Event: card_status
    • Body: payment JSON (status: refused)
  • Refund created / updated
    • Event: refunds
    • Body: refunds JSON for that payment (status: confirmed)
  • Payment cancelled
    • Event: cancel
    • Body: payment JSON (status: cancelled)
  • Payment aborted
    • Event: abort
    • Body: payment JSON (status: aborted)
  • Payment failed
    • Event: timeout / canceled by terminal
    • Body: payment JSON (status: failed)

Implementation notes for the receiver​

  1. Respond quickly with a 2xx status code. The sylq system expects a success response; non-2xx are logged as failures.
  2. Validate the Authorization header Bearer <callback_token> (if you supplied a callback_token).
  3. Security:
    • Only accept HTTPS requests in production.
    • Optionally restrict by source IP / TLS client cert if you have the infrastructure.
  4. Logging: Be aware that messages posted to your callback_url are only displayed in our internal logs for monitoring purposes. They are not stored or resent on demand.

Testing proactive notifications easily​

  • Use a testing tool like Postman to simulate callbacks. Create a remote payment with a callback_url pointing to your mock endpoint.
  • Simulate state changes (via App API calls listed earlier) to trigger the webhook.
  • Confirm that you receive the expected payloads and that the Authorization header matches your callback_token.

We strongly recommend organizing your tests to cover all possible notification cases — not only payment requests, but also refunds (partial or complete), cancellations, timeouts, and other edge cases.