Webhooks

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

The following events are supported:

Cart Completed

Is sent when the consumer has successfully completed payment. The request will additionally contain the payment Id.

Example

{
  "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

Is sent when the cart has been cancelled, this could either be because the user 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.

Example

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

Cart Abandoned

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

Example

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

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.

To configure Basic authentication; in the checkout configuration menu select 'Basic' from the Authentication drop down menu, you will 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.

Basic authentication header format is as follows:
Colon seperated username and password, base64 encoded and then prefixed with the string "BASIC ", supplied as the 'Authorization' header of the http request.

Example

Authorization: "Basic dXNlcm5hbWU6cGFzc3dvcmQ="

Look out for the addition of signature based authentication for payment webhooks; which is currently in development.

You can configure your reconciliation URL in the Reconciliation configuration screen in the Roqqett portal (info / link).

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 accounts 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.

Example

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

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 will be presented with a public key, this will be persisted here during future visits incase 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. Then you may compare this decrypted result with your own caluclated SHA256 signature. If they match then you can be certain that the webhook was signed with the webhook configuration private key; and therefore authentic.

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