Consuming Webhooks - Payloads

Supported webhook events and their respective payloads.

Events

Currently, Safepay supports subscribing to the following events:

payment:created. This event is fired when a payment is captured
refund:created. This event is fired when a refund is made
error:occurred. This event is fired when an error occurs during the payment process

Sample payloads for each of these events are shown below.

payment:created

1
{
2
        "data": {
3
            "token": "C5438LD948188B0GPSH0",
4
            "client_id": "sec_55ca6960-e2ea-4643-b0cf-7cd65a4d3112",
5
            "type": "payment:created",
6
            "endpoint": "https://example.com/listener",
7
            "notification": {
8
                "tracker": "track_gfdkjg80-4knkjnlhknjn9-klnk9knn",
9
                "reference": "514087",
10
                "intent": "PAYFAST",
11
                "fee": "4.92",
12
                "net": "145.08",
13
                "user": "johndoe@gmail.com",
14
                "state": "PAID",
15
                "amount": "150",
16
                "currency": "PKR",
17
                "metadata": {
18
                    "order_id": "XG102312",
19
                    "source": "shopify"
20
                }
21
            },
22
            "delivery_attempts": 1,
23
            "resource": "notification",
24
            "next_attempt_at": "2021-10-01T09:05:33Z",
25
            "created_at": "2021-10-01T09:05:34Z"
26
        }
27
    }

refund:created

1
{
2
        "data": {
3
            "token": "C243APO942228CP0L5GF",
4
            "client_id": "sec_55ca6960-e2ea-4643-b0cf-7cd65a4d3112",
5
            "type": "payment:created",
6
            "endpoint": "https://example.com/listener",
7
            "notification": {
8
                "tracker": "track_gfdkjg80-4knkjnlhknjn9-klnk9knn",
9
                "intent": "PAYFAST",
10
                "user": "johndoe@gmail.com",
11
                "state": "PARTIALLY REFUNDED",
12
                "amount": "25",
13
                "balance": "125",
14
                "currency": "PKR",
15
                "metadata": {
16
                    "order_id": "XG102312",
17
                    "source": "shopify"
18
                }
19
            },
20
            "delivery_attempts": 1,
21
            "resource": "notification",
22
            "next_attempt_at": "2021-10-01T09:05:33Z",
23
            "created_at": "2021-10-01T09:05:34Z"
24
        }
25
    }

error:occurred

1
{
2
        "data": {
3
            "token": "C59KV5CBCV49VMOLCMVG",
4
            "client_id": "sec_55ca6960-e2ea-4643-b0cf-7cd65a4d3112",
5
            "type": "error:occurred",
6
            "endpoint": "https://example.com/listener",
7
            "notification": {
8
                "tracker": "track_5b694027-7947-4187-bbaa-8585a07c0cbc",
9
                "intent": "PAYFAST",
10
                "message": "55 : Incorrect OTP",
11
                "metadata": {
12
                    "order_id": "XG102312",
13
                    "source": "shopify"
14
                }
15
            },
16
            "delivery_attempts": 1,
17
            "resource": "notification",
18
            "next_attempt_at": "2021-10-01T09:05:33Z",
19
            "created_at": "2021-10-01T09:05:34Z"
20
        }
21
    }

Payments 2.0 Events

For Payments 2.0, Safepay supports a broader suite of events:

Payment Events

payment.succeeded. This event is fired when a payment is captured
payment.failed. This event is fired when an error occurs during the payment process
payment.reversed. This event is fired when a refund is made
authorization.reversed. This event is fired when an authorization has been reversed
void.succeeded. This event is fired when a payment or refund has been voided

Sample payloads are shown below.

payment.succeeded

1
{
2
        "token":"evt_64b3218e-f65c-45a9-96b0-fe4e293bb879",
3
        "version":"2.0.0",
4
        "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554",
5
        "type":"payment.succeeded",
6
        "endpoint":"http://example.com",
7
        "data":{
8
            "tracker":"track_06ee38cb-981d-4158-819f-7231f28314e4",
9
            "intent":"CYBERSOURCE",
10
            "state":"TRACKER_ENDED",
11
            "net":43525,
12
            "fee":1475,
13
            "customer_email":"hzee@gmail.com",
14
            "amount":45000,
15
            "currency":"PKR",
16
            "metadata":{
17
              "order_id":"AX-09u812312",
18
              "source":"shopify"
19
            },
20
            "charged_at":{
21
              "seconds":1698754230,
22
              "nanos":752997627
23
            }
24
        },
25
        "created_at":{
26
            "seconds":1698754230,
27
            "nanos":912705711
28
        }
29
      }

payment.failed

1
{
2
        "token":"evt_e7069e13-e4a4-4518-b5ce-ee42e62b6797",
3
        "version":"2.0.0",
4
        "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554",
5
        "type":"payment.failed",
6
        "endpoint":"http://example.com",
7
        "data":{
8
            "tracker":"track_138cf593-3d3f-4d54-b9c6-27a510afb780",
9
            "intent":"CYBERSOURCE",
10
            "state":"TRACKER_ENROLLED",
11
            "customer_email":"hzee@gmail.com",
12
            "metadata":{},
13
            "category":"PAYMENT_METHOD_ERROR",
14
            "code":403,
15
            "message":"The card you have used has been flagged as either stolen or lost. ",
16
            "failed_at":{
17
              "seconds":1698754648,
18
              "nanos":494424793
19
            }
20
        },
21
        "created_at":{
22
            "seconds":1698754648,
23
            "nanos":589390626
24
        }
25
      }

payment.refunded

1
{
2
        "token":"evt_48431483-2111-4328-8729-309c96c7a0f6",
3
        "version":"2.0.0",
4
        "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554",
5
        "type":"payment.refunded",
6
        "endpoint":"http://example.com",
7
        "data":{
8
            "tracker":"track_06ee38cb-981d-4158-819f-7231f28314e4",
9
            "intent":"CYBERSOURCE",
10
            "state":"TRACKER_PARTIAL_REFUND",
11
            "customer_email":"hzee@gmail.com",
12
            "balance":44000,
13
            "currency":"PKR",
14
            "metadata":{
15
              "order_id":"AX-09u812312",
16
              "source":"shopify"
17
            },
18
            "refund_amount":1000,
19
            "refunded_at":{
20
              "seconds":1698758038,
21
              "nanos":682810001
22
            }
23
        },
24
        "created_at":{
25
            "seconds":1698758038,
26
            "nanos":880931084
27
        }
28
      }

authorization.reversed

1
{
2
        "token":"evt_91ff4cf9-06e5-47ef-a110-2c82dccc8235",
3
        "version":"2.0.0",
4
        "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554",
5
        "type":"authorization.reversed",
6
        "endpoint":"http://example.com",
7
        "data":{
8
            "tracker":"track_c3f7bc7e-7ae5-4e8a-b31d-b5bc74fa7e38",
9
            "intent":"CYBERSOURCE",
10
            "state":"TRACKER_REVERSED",
11
            "customer_email":"hzee@gmail.com",
12
            "metadata":{},
13
            "reversed_authorization_id":"auth_9dce2ce2-4f65-4aa7-a1ff-8a9a3d6e64b3",
14
            "reversed_at":{
15
              "seconds":1698757881,
16
              "nanos":354475053
17
            }
18
        },
19
        "created_at":{
20
            "seconds":1698757881,
21
            "nanos":493894470
22
        }
23
      }

void.succeeded

1
{
2
        "token":"evt_846f361c-f3f8-492d-a3e9-f895ea9c91ce",
3
        "version":"2.0.0",
4
        "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554",
5
        "type":"void.succeeded",
6
        "endpoint":"http://example.com",
7
        "data":{
8
          "tracker":"track_d927a58c-83cf-4e1a-904c-1b439fa913a4",
9
          "intent":"CYBERSOURCE",
10
          "state":"TRACKER_VOIDED",
11
          "customer_email":"hzee@gmail.com",
12
          "metadata":{
13
              "order_id":"AX-09u812312",
14
              "source":"shopify"
15
          },
16
          "void_type":"CAPTURE",
17
          "voided_charge_id":"cap_d40b58da-cdba-4843-92ac-eb046ed325de",
18
          "voided_at":{
19
              "seconds":1698758174,
20
              "nanos":715064342
21
          }
22
        },
23
        "created_at":{
24
          "seconds":1698758174,
25
          "nanos":872747134
26
        }
27
      }

Subscription Events

subscription.created. This event is fired when a customer subscribes to a recurring payment plan
subscription.canceled. This event is fired when a subscription is canceled
subscription.ended. This event is fired when all billing cycles of a recurring payment subscription have been paid
subscription.paused. This event is fired when a subscription has been paused
subscription.resumed. This event is fired when a paused subscription has been resumed
subscription.payment.succeeded. This event is fired when a recurring payment cycle has been paid
subscription.payment.failed. This event is fired when a recurring payment cycle was not paid

Sample payloads are shown below.

subscription.created

1
{
2
        "token":"evt_071ce9e0-6e95-4761-87a1-1de08be5a0c3",
3
        "version":"2.0.0",
4
        "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554",
5
        "type":"subscription.created",
6
        "endpoint":"http://example.com",
7
        "data":{
8
          "id":"sub_73f6b269-4c8e-44d6-b55e-b982ef5f2835",
9
          "plan_id":"plan_c749c21e-f075-4cc4-8d3d-4e44e6bf3623",
10
          "customer_email":"hzaidi@getsafepay.com",
11
          "status":"INCOMPLETE",
12
          "billing_cycle_anchor":{
13
              "seconds":1698758572,
14
              "nanos":667943762
15
          },
16
          "amount":100000,
17
          "currency":"PKR",
18
          "balance":"0",
19
          "started_at":{
20
              "seconds":1698758572,
21
              "nanos":667943762
22
          },
23
          "expires":true,
24
          "current_period_start_date":{
25
              "seconds":1698758572,
26
              "nanos":667943762
27
          },
28
          "current_period_end_date":{
29
              "seconds":1698758631,
30
              "nanos":667943762
31
          },
32
          "number_of_billing_cycles":2,
33
          "updated_at":{
34
              "seconds":1698758572,
35
              "nanos":667943762
36
          },
37
          "created_at":{
38
              "seconds":1698758572,
39
              "nanos":667943762
40
          }
41
        },
42
        "created_at":{
43
          "seconds":1698758572,
44
          "nanos":935293429
45
        }
46
      }

subscription.canceled

1
{
2
        "token":"evt_3557f8ba-e411-48b7-9d13-c0a355873735",
3
        "version":"2.0.0",
4
        "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554",
5
        "type":"subscription.canceled",
6
        "endpoint":"http://example.com",
7
        "data":{
8
            "id":"sub_479236af-b767-473b-acdf-6855db20c023",
9
            "plan_id":"plan_22933989-a533-44d6-80d2-c1816571f451",
10
            "customer_email":"hzaidi@getsafepay.com",
11
            "status":"CANCELED",
12
            "amount":300000,
13
            "currency":"PKR",
14
            "balance":"0",
15
            "canceled_at":{
16
              "seconds":1698759228
17
            },
18
            "updated_at":{
19
              "seconds":1698759228
20
            },
21
            "created_at":{
22
              "seconds":1698759224
23
            }
24
        },
25
        "created_at":{
26
            "seconds":1698759227,
27
            "nanos":992878718
28
        }
29
      }

subscription.ended

1
{
2
        "token":"evt_1ba6f54f-4ed9-4e5a-b7a1-cd45598ec432",
3
        "version":"2.0.0",
4
        "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554",
5
        "type":"subscription.ended",
6
        "endpoint":"http://example.com",
7
        "data":{
8
          "id":"sub_73f6b269-4c8e-44d6-b55e-b982ef5f2835",
9
          "plan_id":"plan_c749c21e-f075-4cc4-8d3d-4e44e6bf3623",
10
          "customer_email":"hzaidi@getsafepay.com",
11
          "status":"ENDED",
12
          "amount":100000,
13
          "currency":"PKR",
14
          "balance":"0",
15
          "updated_at":{
16
              "seconds":1698758619
17
          },
18
          "created_at":{
19
              "seconds":1698758573
20
          }
21
        },
22
        "created_at":{
23
          "seconds":1698758645,
24
          "nanos":20656046
25
        }
26
      }

subscription.paused

1
{
2
        "token":"evt_3ebf1fea-b065-4a7d-925c-199245f98114",
3
        "version":"2.0.0",
4
        "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554",
5
        "type":"subscription.paused",
6
        "endpoint":"http://example.com",
7
        "data":{
8
            "id":"sub_7e48edb7-daf8-47bf-9679-5b1cf24ff614",
9
            "plan_id":"plan_22933989-a533-44d6-80d2-c1816571f451",
10
            "customer_email":"hzaidi@getsafepay.com",
11
            "status":"PAUSED",
12
            "billing_cycle_anchor":{
13
              "seconds":1698760037
14
            },
15
            "amount":300000,
16
            "currency":"PKR",
17
            "balance":"0",
18
            "paused_at":{
19
              "seconds":1698760042
20
            },
21
            "updated_at":{
22
              "seconds":1698760042
23
            },
24
            "created_at":{
25
              "seconds":1698760037
26
            }
27
        },
28
        "created_at":{
29
            "seconds":1698760042,
30
            "nanos":438161220
31
        }
32
      }

subscription.resumed

1
{
2
        "token":"evt_9e0c9f81-8607-4fd7-936c-56fed465ee90",
3
        "version":"2.0.0",
4
        "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554",
5
        "type":"subscription.resumed",
6
        "endpoint":"http://example.com",
7
        "data":{
8
            "id":"sub_5726bec7-1d2a-424d-a650-04b963c0e854",
9
            "plan_id":"plan_c749c21e-f075-4cc4-8d3d-4e44e6bf3623",
10
            "customer_email":"hzaidi@getsafepay.com",
11
            "status":"ACTIVE",
12
            "billing_cycle_anchor":{
13
              "seconds":1698760196
14
            },
15
            "amount":100000,
16
            "currency":"PKR",
17
            "balance":"0",
18
            "resumed_at":{
19
              "seconds":1698760196
20
            },
21
            "updated_at":{
22
              "seconds":1698760196
23
            },
24
            "created_at":{
25
              "seconds":1698760185
26
            }
27
        },
28
        "created_at":{
29
            "seconds":1698760196,
30
            "nanos":518876958
31
        }
32
      }

subscription.payment.succeeded

1
{
2
        "token":"evt_ea9ab1a2-4a3b-478a-ac82-cb986b60242e",
3
        "version":"2.0.0",
4
        "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554",
5
        "type":"subscription.payment.succeeded",
6
        "endpoint":"http://example.com",
7
        "data":{
8
           "id":"sub_73f6b269-4c8e-44d6-b55e-b982ef5f2835",
9
           "plan_id":"plan_c749c21e-f075-4cc4-8d3d-4e44e6bf3623",
10
           "customer_email":"hzaidi@getsafepay.com",
11
           "status":"ACTIVE",
12
           "billing_cycle_anchor":{
13
              "seconds":1698758633
14
           },
15
           "amount":100000,
16
           "currency":"PKR",
17
           "balance":"0",
18
           "current_period_start_date":{
19
              "seconds":1698758633
20
           },
21
           "current_period_end_date":{
22
              "seconds":1698758692
23
           },
24
           "last_paid_date":{
25
              "seconds":1698758586,
26
              "nanos":667158380
27
           },
28
           "current_billing_cycle":1,
29
           "updated_at":{
30
              "seconds":1698758573
31
           },
32
           "created_at":{
33
              "seconds":1698758573
34
           },
35
           "transaction_id":"txn_8b29b706-168d-4b38-991c-ac77620a29b7",
36
           "transaction_status":"COMPLETE"
37
        },
38
        "created_at":{
39
           "seconds":1698758586,
40
           "nanos":858671671
41
        }
42
      }

subscription.payment.failed

1
{
2
        "token": "evt_3f8ee089-c083-4475-af48-036b38140053",
3
        "version": "2.0.0",
4
        "merchant_api_key": "sec_d2ec84f8-eae4-4e50-80ba-dad01c7bab83",
5
        "type": "subscription.payment.failed",
6
        "endpoint": "https://example.com",
7
        "data": {
8
          "id": "sub_b55072cf-2556-4c17-82b4-dae075960df8",
9
          "plan_id": "plan_8ae8e989-08fd-47dd-9a95-04056c83b6fa",
10
          "customer_email": "hzaidi@getsafepay.com",
11
          "status": "UNPAID",
12
          "billing_cycle_anchor": {
13
            "seconds": 1710824626
14
          },
15
          "amount": 405100,
16
          "currency": "PKR",
17
          "balance": "0",
18
          "updated_at": {
19
            "seconds": 1710824626
20
          },
21
          "created_at": {
22
            "seconds": 1710824626
23
          },
24
          "transaction_id": "txn_b54bb42c-bc55-481b-b1d9-fd945f44f8c3",
25
          "transaction_status": "FAILED",
26
          "transaction_error_code": "NONE_TRANSACTION_FAILURE_CODE",
27
          "transaction_error_message": "unrecognized or unsupported action kind"
28
        },
29
        "created_at": {
30
          "seconds": 1710825617,
31
          "nanos": 655468013
32
        }
33
      }

Signature verification