Webhooks

Overview

Set up your payment webhooks endpoint in the checkout configuration screen in the Roqqett portal. Once configured, the service will send a webhook every time a cart reaches a final state, keeping you informed of carts that were completed, timed out, or cancelled.

Cart Completed

This webhook event is sent when the consumer has successfully completed the payment. The request will additionally contain the payment ID.

{
  "eventType": "cart_completed",
  "cartId": "94c92315-53f0-4784-b40d-b7cc3e2f8c73",
  "merchantCartId": "UEhQU0VTU0lEPWU1aGs4YWNrZjJrZ3RpODg2bWNrNTBvYzcy",
  "paymentId": "d3579e67-f9f5-4bd8-9e32-a043c91fea24",
  "orderId":"6bcafe48-c6ff-11ec-9d64-0242ac120002",
  "dateTime": "2021-08-18 20:08:04"
}

Cart Cancelled

This webhook event is sent when the cart has been cancelled, this could either be because the customer has cancelled out of the process and returned to your checkout, or if your backend has specifically cancelled the session via a call to /cart/{cartId}/cancel via HTTP POST.

{
  "eventType": "cart_cancelled",
  "cartId": "252e18db-e6d1-493f-9bc5-1952b1530b57",
  "merchantCartId": "441b9bd8-b942-4f96-8693-e4bf6df28368",
  "dateTime": "2021-08-18 20:08:04"
}

Cart Abandoned

This webhook event is sent when the cart expires, which is currently 20 minutes after creation. If the customer's payment is in a pending state at the expiry time, then the cart won't be abandoned and when the bank subsequently confirms the payment is completed, a cart_completed event will be sent. However, if the customer's payment is rejected by the bank, then a cart_abandoned event will be sent.

{
  "eventType": "cart_abandoned",
  "cartId": "eee06b8c-7d2f-4238-b519-c4f2666311f8",
  "merchantCartId": "UEhQU0VTU0lEPWU1aDk4N3dzOTg3YThkN2FzNTBvYzcy",
  "dateTime": "2021-08-18 20:08:04"
}

Payment webhook authentication

In order to guarantee the authenticity of webhooks that are transmitted to your payments webhook URL we provide the option to add Http Basic authentication.

In the checkout configuration, menu select Basic from the Authentication dropdown. You'll then be prompted to input a username and password.

The specified username and password will subsequently be provided (in accordance with RFC 7235) as a header alongside payment webhooks that are transmitted by us to your webhook URL. This header may then be parsed and validated by your server-side logic.

The Basic authentication header format is a colon-separated username and password, base64 encoded, and then prefixed with the string Basic, supplied as the Authorization header of the HTTP request.

Authorization: "Basic dXNlcm5hbWU6cGFzc3dvcmQ="

Reconciliation webhooks

You can configure your reconciliation URL in the Reconciliation tab in the Settings area of the Roqqett portal.

Reconciliation webhooks operate in a similar manner to the payment webhook detailed above, but are only transmitted when a successful Roqqett payment has been positively reconciled against a transaction from the corresponding bank account's AIS transaction feed.

A reconciliation webhook is also sent if the payment and transaction have been manually reconciled in the Roqqett portal.

Cleared

Cleared is the only status that a reconciliation webhook will be dispatched with. Once a Roqqett payment is successfully matched with a transaction from the bank account, it is considered cleared.

{
  "merchantCartId": "441b9bd8-b942-4f96-8693-e4bf6df28368",
  "paymentId": "d04a6a16-afe4-4376-83ff-d8cb5e62ed8a",
  "reconStatus": "CLEARED"
}

Reconciliation webhook authentication

To provide a guarantee of the authenticity of reconciliation webhooks, we provide signature-based authentication. Once you have configured the reconciliation webhook URL in the Roqqett portal, you'll be presented with a public key. This will be persisted here during future visits in case you need to fetch it again.

Signature generation

Before a reconciliation webhook is transmitted, the JSON HTTP request body is stringified and fed into a hashing algorithm (SHA256). The hash message is encrypted with the private key (which Roqqett does not disclose) associated with the webhook configuration and the resultant cipher is then included as a HTTP header with the webhook sent to your configured URL.

Signature validation

Upon receiving a webhook, you may use the public key associated with the webhook configuration (obtained from the Roqqett portal) to decrypt the signature header provided alongside the webhook. You can then compare this decrypted result with your own calculated SHA256 signature. If they match, then you can be certain that the webhook was signed with the webhook configuration private key and is therefore authentic.

Refund webhooks

Completed refunds will be notified via the reconciliation webhook detailed above, if reconciliation is enabled for your organisation.