Cards & Wallets · PaySuite payment page · Advanced features

Notifications and callbacks

Keep your back-office systems in sync by receiving notifications and callbacks when transactions finish processing.

Notifications are server-to-server messages sent after a transaction has completed. You can provide a session.transactionNotification.url when you initialise the session, or set a default URL during boarding. If we cannot deliver on the first attempt, we retry. A notification is considered delivered when we receive an HTTP 200 within 10 seconds.

In-flight callbacks allow you to take actions while a transaction is still being processed, for example to approve or reject a payment before it completes. Provide session.preAuthCallback.url for a callback before the transaction is sent for authorisation, and session.postAuthCallback.url for one after it is authorised but before it is finalised.

Requesting notifications and callbacks

Add the URLs you want to use to the session object of the session initialisation request, each with the format you want to receive. The example below requests all three.

Payment session with a notification and both in-flight callbacks
EndpointDefinition
POST /hosted/rest/sessions/{instId}/payments
Request body
{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    },
    "transactionNotification": {
      "url": "https://www.example.com/transactionNotification",
      "format": "REST_JSON"
    },
    "preAuthCallback": {
      "url": "https://www.example.com/preAuthCallback",
      "format": "REST_JSON"
    },
    "postAuthCallback": {
      "url": "https://www.example.com/postAuthCallback",
      "format": "REST_JSON"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP",
      "amount": {
        "fixed": 25.00
      }
    },
    "merchantReference": "aReference"
  }
}
cURL
curl -X POST "{targetEnvironmentPath}/hosted/rest/sessions/{instId}/payments" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    },
    "transactionNotification": {
      "url": "https://www.example.com/transactionNotification",
      "format": "REST_JSON"
    },
    "preAuthCallback": {
      "url": "https://www.example.com/preAuthCallback",
      "format": "REST_JSON"
    },
    "postAuthCallback": {
      "url": "https://www.example.com/postAuthCallback",
      "format": "REST_JSON"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP",
      "amount": {
        "fixed": 25.00
      }
    },
    "merchantReference": "aReference"
  }
}'
Response
HTTP/1.1 201 Created

{
  "sessionId": "SMjqPvAq2y39PP5qaNpOZ-oeQ",
  "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjqPvAq2y39PP5qaNpOZ-oeQ/begin/SMjqPvAq2y39PP5qaNpOZ-oeQ",
  "status": "SUCCESS"
}

Details provided on the session take precedence over any defaults set on your account.

See notifications for the message formats and retry behaviour, and in-flight call-backs for the callback request and response formats and the rules your handler must follow.