Skip to main content
Version: 3.0.0 (current)

4. Handle completed session

Receiving hooks

You should configure hooks when creating sessions that you listen to to know when a session has completed. Hooks sent by Briqpay will contain the event type, status, sessionId and merchant references. The most common Payments use-case will look like this:

Adding payment hooks when creating a session

"hooks": [
{
"eventType": "order_status",
"statuses": ["order_pending", "order_rejected", "order_cancelled", "order_approved_not_captured"],
"method": "POST",
"url": "https://example.com/notifications"
},
{
"eventType": "capture_status",
"statuses": ["pending", "approved", "rejected"],
"method": "POST",
"url": "https://example.com/notifications"
},
{
"eventType": "refund_status",
"statuses": ["pending", "approved", "rejected"],
"method": "POST",
"url": "https://example.com/notifications"
}
],

Since hooks are unauthenticated, you must read the session to verify that the hook is valid.

Payment sessions will be placed with a pending status when completed. Usually orders will leave the pending status within a few minutes, some payment methods excluded. The first hook you receive will usually have the 'order_pending' status meaning you should create your order in a pending state and wait. When you receive a hook with the 'order_approved_not_captured' status, you can create/move your order to a 'placed' status. If for some reason the order was rejected, it will have the 'order_rejected' status.

Example of a capture webhook body sent to you by us

{
"event": "capture_status",
"status": "approved",
"sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d",
"captureId": "a3811397-a1fc-44f0-99fd-d134063c9c47",
"autoCaptured": true
}

WARNING: These webhooks are unauthenticated so you must read the session after receiving events to validate the event.

The hook response consists of "event", "status" and "sessionId". If using "GET", the response parameters will be sent as query parameters and when using "POST" it will be sent as the request body.

Example response payloads

session_status

{
"event": "session_status",
"status": "completed",
"sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d"
}

order_status:

{
"event": "order_status",
"status": "order_approved_not_captured",
"sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d"
}

capture_status:

{
"event": "capture_status",
"status": "approved",
"sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d",
"captureId": "a3811397-a1fc-44f0-99fd-d134063c9c47",
"autoCaptured": true,
"isPreExistingCapture": true
}

refund_status:

{
"event": "refund_status",
"status": "approved",
"sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d",
"refundId": "a3811397-a1fc-44f0-99fd-d134063c9c47"
}