Webhooks and GET calls

You will receive a webhook when there is a change in payment handle status or payment status. You can get the status by executing the GET payment handle and payments calls.

Webhooks

Scenario 1: Payment call is made before the customer completes the transaction on redirection link.

Payment Handle is Payable (It indicates that you redirected customer to redirection link returned in payment handle response)
You makes /payments call
Customer completes the Payment

Event	Webhook
Request is sent /paymentHandle Success response is received	NA
When customer is redirected to Safetypay Express link	Payment Handle Payable webhook
When /payments call is made	Payment Handle Completed webhook Payment Processing webhook
When customer completes the transaction on redirection link	Payment Completed webhook

Scenario 2: The payment’s call is made after the customer finishes the transaction on the redirection link.

Payment Handle is Payable (It indicates that you redirected customer to redirection link returned in Payment handle response)
Customer completes the transaction
You makes /payments call

Event

Status

Request is sent /paymentHandle

Success response is received

When customer is redirected to SafetyPay Express link

Payment Handle Payable webhook

When /payments call is made

Payment Handle Completed webhook

Payment Completed webhook

Settlement Completed webhook

Scenario 3: Auto-settle (Auto-payment) Feature

You must always make Payments API call once payment handle is Payable. However, if you do not make Payments API call and Payment Handle is Payable and then our system makes Payments call on your behalf.

Payment Handle is Payable (It indicates that you redirected customer to redirection link returned in Payment handle response)
Customer completes the transaction
Payment Handle TTL becomes zero
No /payments call is made from your end

Event

Status

Request is sent /paymentHandle

Success response is received

When customer is redirected to Safetypay Express link

Payment Handle Payable webhook

When Payment Handle TTL becomes zero and no /payments call is made by you

Payment Handle Expired webhook with status & statusReason as

"status": "EXPIRED" "statusReason": "AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE" statuReason:"AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE" indicates that Paysafe system is going to make /payments call on your behalf.

/payments call is made by our system

Payment Completed webhook with statusReason as

"statusReason": "AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE"

Settlement Completed webhook

Scenario 4: Auto-settle (Auto-payment) Feature

You must always make Payments API call once Payment handle is Payable. However, if you do not make Payments API call and Payment Handle is Payable and then our system makes Payments call on your behalf.

Payment Handle is Payable (It indicates that you redirected customer to redirection link returned in Payment handle response)
Customer does not complete the transaction
Payment Handle TTL becomes zero
No /payments call is made by you

Event	Status
Request is sent /paymentHandle Success response is received	NA
When customer is redirected to Safetypay Express link	Payment Handle Payable webhook
When Payment Handle TTL becomes zero and no /payments call is made by you	Payment Handle Expired webhook with status & statusReason as "status": "EXPIRED" "statusReason": "AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE" statusReason:"AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE" indicates that Paysafe system is going make /payments call on your behalf. /payments call is made by system Payments Processing webhook with statusReason as "statusReason": "AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE"
When customer completes the transaction on redirection link	Payment Completed webhook with statusReason as "statusReason": "AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE"

Scenario 5: When the customer is not redirected

Payment Handle is not Payable
- It indicates that you did not redirect customer to redirection link returned in payment handle response
- Customer did not click link or aborted transaction
Payment Handle TTL becomes zero

Event

Status

Request is sent /paymentHandle

Success response is received

When Payment Handle TTL becomes zero

Payment Handle Expired webhook with status and status reason as

"status": "EXPIRED"

"statusReason": "AUTH_EXPIRED"

statusReason:"AUTH_EXPIRED" indicates that Paysafe system is NOT going make /payments call on your behalf.

/payments call is NOT made by system. Paysafe system makes auto-settle (auto-payment) transaction only when payment handle is Payable and Payments are not made by you.

Sample Webhook Packets

Payment Handle Payable

{

  "payload": {

    "accountId": "1002495240",

    "id": "691eb499-740a-447e-90c4-c7fdf1d7fcab",

    "merchantRefNum": "7cb52ed1-4d7f-4b4c-86d9-1867bf6be577",

    "paymentHandleToken": "Payment Handle8adi9300Lw80Iu",

    "transactionType": "PAYMENT",

    "amount": 1000,

    "currencyCode": "<Currency>",

    "status": "PAYABLE",

    "paymentType": "<PaymentMethodName>",

    "statusTime": "2023-05-04T05:45:43Z",

    "updatedTime": "2023-05-04T05:45:43Z",

    "gatewayReconciliationId": "c9c31a38-b050-4e8b-80e3-1ec3ea7d383c",

    "customerIp": "213.208.158.212",

    "profile": {

      "email": "BRTESTQA202_01@gmail.com"

    },

    "usage": "SINGLE_USE",

    "executionMode": "SYNCHRONOUS",

    "gatewayResponse": {

      "operationId": "0123124567278578",

      "id": "c9c31a38-b050-4e8b-80e3-1ec3ea7d383c",

      "processor": "SAFETYPAY"

    },

    "txnTime": "2023-05-04T05:45:21Z"

  },

  "eventType": "PAYMENT_HANDLE_PAYABLE",

  "attemptNumber": "1",

  "resourceId": "691eb499-740a-447e-90c4-c7fdf1d7fcab",

  "eventDate": "2023-05-04T05:45:21Z",

  "links": [

    {

      "href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002495240/paymenthandles/691eb499-740a-447e-90c4-c7fdf1d7fcab",

      "rel": "payment_handle"

    }

  ],

  "mode": "live",

  "eventName": "PAYMENT_HANDLE_PAYABLE"

}

Payment Handle Completed

{

  "payload": {

    "accountId": "1002622990",

    "id": "248648d4-6374-4037-a000-1e6055b0522c",

    "merchantRefNum": "1682935290",

    "paymentHandleToken": "Payment HandlexpvnS0kz778OTP",

    "transactionType": "PAYMENT",

    "amount": 1000,

    "currencyCode": "<Currency>",

    "status": "COMPLETED",

    "paymentType": "<PaymentMethodName>",

    "statusTime": "2023-05-01T10:03:31Z",

    "updatedTime": "2023-05-01T10:03:31Z",

    "gatewayReconciliationId": "b0230487-769b-46fd-ac8d-c3c8fc854d65",

    "customerIp": "115.114.129.142",

    "profile": {

      "email": "CRCASHUSDTEST0501_01@gmail.com"

    },

    "usage": "SINGLE_USE",

    "executionMode": "SYNCHRONOUS",

    "gatewayResponse": {

      "operationId": "0123121563603103",

      "id": "b0230487-769b-46fd-ac8d-c3c8fc854d65",

      "processor": "SAFETYPAY",

      "status": "102"

    },

    "txnTime": "2023-05-01T10:01:29Z"

  },

  "eventType": "PAYMENT_HANDLE_COMPLETED",

  "attemptNumber": "1",

  "resourceId": "248648d4-6374-4037-a000-1e6055b0522c",

  "eventDate": "2023-05-01T10:01:29Z",

  "links": [

    {

      "href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002622990/paymenthandles/248648d4-6374-4037-a000-1e6055b0522c",

      "rel": "payment_handle"

    }

  ],

  "mode": "live",

  "eventName": "PAYMENT_HANDLE_COMPLETED"

}

Payment Handle Expired with "statusReason": "AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE"

{

  "payload": {

    "accountId": "1002495240",

    "id": "691eb499-740a-447e-90c4-c7fdf1d7fcab",

    "merchantRefNum": "7cb52ed1-4d7f-4b4c-86d9-1867bf6be577",

    "paymentHandleToken": "PH8adi9300Lw80Iu",

    "transactionType": "PAYMENT",

    "amount": 1000,

    "currencyCode": "<currency>",

    "status": "EXPIRED",

    "statusReason": "AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE",

    "paymentType": "<paymentmethodname>",

    "statusTime": "2023-05-04T06:00:25Z",

    "updatedTime": "2023-05-04T06:00:25Z",

    "gatewayReconciliationId": "c9c31a38-b050-4e8b-80e3-1ec3ea7d383c",

    "customerIp": "213.208.158.212",

    "profile": {

      "email": "BRTESTQA202_01@gmail.com"

    },

    "usage": "SINGLE_USE",

    "executionMode": "SYNCHRONOUS",

    "gatewayResponse": {

      "operationId": "0123124567278578",

      "id": "c9c31a38-b050-4e8b-80e3-1ec3ea7d383c",

      "processor": "SAFETYPAY",

      "status": "101"

    },

    "txnTime": "2023-05-04T05:45:21Z"

  },

  "eventType": "PAYMENT_HANDLE_EXPIRED",

  "attemptNumber": "1",

  "resourceId": "691eb499-740a-447e-90c4-c7fdf1d7fcab",

  "eventDate": "2023-05-04T05:45:21Z",

  "links": [

    {

      "href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002495240/paymenthandles/691eb499-740a-447e-90c4-c7fdf1d7fcab",

      "rel": "payment_handle"

    }

  ],

  "mode": "live",

  "eventName": "PAYMENT_HANDLE_EXPIRED"

}

Payment Handle Expired "statusReason": "AUTH_EXPIRED"

{

  "payload": {

    "accountId": "1002495240",

    "id": "da5f9715-6ff8-41da-b467-078c727a501f",

    "merchantRefNum": "9b2fd028-bd35-4fc3-86fa-5ea70b81d844",

    "paymentHandleToken": "PHL3XRsJo1gnKzmG",

    "transactionType": "PAYMENT",

    "amount": 500000,

    "currencyCode": "<Currency>",

    "status": "EXPIRED",

    "statusReason": "AUTH_EXPIRED",

    "paymentType": "<PaymentMethodName>",

    "statusTime": "2023-05-04T06:02:24Z",

    "updatedTime": "2023-05-04T06:02:24Z",

    "gatewayReconciliationId": "e6e433fb-7463-4f4b-ac96-3cbbfa9f86eb",

    "customerIp": "213.208.158.212",

    "profile": {

      "email": "BRTESTQA202_01@gmail.com"

    },

    "usage": "SINGLE_USE",

    "executionMode": "SYNCHRONOUS",

    "gatewayResponse": {

      "operationId": "0123124567283583",

      "id": "e6e433fb-7463-4f4b-ac96-3cbbfa9f86eb",

      "processor": "SAFETYPAY"

    },

    "txnTime": "2023-05-04T05:46:03Z"

  },

  "eventType": "PAYMENT_HANDLE_EXPIRED",

  "attemptNumber": "1",

  "resourceId": "da5f9715-6ff8-41da-b467-078c727a501f",

  "eventDate": "2023-05-04T05:46:03Z",

  "links": [

    {

      "href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002495240/paymenthandles/da5f9715-6ff8-41da-b467-078c727a501f",

      "rel": "payment_handle"

    }

  ],

  "mode": "live",

  "eventName": "PAYMENT_HANDLE_EXPIRED"

}

Payment Handle Error

{

  "payload": {

    "accountId": "1002652080",

    "id": "587ca09e-e4a9-4270-af7a-48398aee7518",

    "merchantRefNum": "691cce16-9d48-4817-bdad-80dbcde976b1",

    "paymentHandleToken": "PHMjKuWiwIaIwmM0",

    "transactionType": "PAYMENT",

    "amount": 1000,

    "currencyCode": "<Curency>",

    "status": "ERROR",

    "paymentType": "<PaymentMethodName>",

    "statusTime": "2023-05-04T05:44:35Z",

    "updatedTime": "2023-05-04T05:44:35Z",

    "gatewayReconciliationId": "a814b95c-a7fd-4682-89b1-46c39daa2be2",

    "customerIp": "213.208.158.212",

    "profile": {

      "email": "BRTESTQA202_01@gmail.com"

    },

    "usage": "SINGLE_USE",

    "executionMode": "SYNCHRONOUS",

    "txnTime": "2023-05-04T05:44:35Z",

    "error": {

      "code": "5068",

      "message": "Field error(s)",

      "details": [

        "Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected."

      ]

    }

  },

  "eventType": "PAYMENT_HANDLE_ERRORED",

  "attemptNumber": "1",

  "resourceId": "587ca09e-e4a9-4270-af7a-48398aee7518",

  "eventDate": "2023-05-04T05:44:35Z",

  "links": [

    {

      "href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002652080/paymenthandles/587ca09e-e4a9-4270-af7a-48398aee7518",

      "rel": "payment_handle"

    }

  ],

  "mode": "live",

  "eventName": "PAYMENT_HANDLE_ERRORED",

  "EventName": "PAYMENT_HANDLE_ERRORED"

}

Payment Processing

{

  "payload": {

    "accountId": "1002495240",

    "id": "7422f92f-fb13-4f51-bc00-86bee277a506",

    "merchantRefNum": "523a463c-c6a1-4e64-ace9-0c1161b9a31a",

    "paymentHandleToken": "PHC0uHklty7AIXEI",

    "amount": 500000,

    "currencyCode": "<currency>",

    "status": "PROCESSING",

    "gatewayResponse": {

      "operationId": "0123124567407707",

      "id": "b08562c0-9e7a-45e6-a8f2-17eaf669a38a",

      "processor": "SAFETYPAY",

      "status": "101"

    },

    "paymentType": "<PaymentMethodName>",

    "source": "SingleAPI",

    "availableToSettle": 0,

    "txnTime": "2023-05-04T08:20:29Z",

    "customerIp": "213.208.158.212",

    "profile": {

      "email": "BRTESTQA202_01@gmail.com"

    },

    "settleWithAuth": true,

    "statusTime": "2023-05-04T08:21:34Z",

    "updatedTime": "2023-05-04T08:21:34Z",

    "gatewayReconciliationId": "b08562c0-9e7a-45e6-a8f2-17eaf669a38a"

  },

  "eventType": "PAYMENT_PROCESSING",

  "attemptNumber": "1",

  "resourceId": "7422f92f-fb13-4f51-bc00-86bee277a506",

  "eventDate": "2023-05-04T08:20:29Z",

  "links": [

    {

      "href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002495240/payments/7422f92f-fb13-4f51-bc00-86bee277a506",

      "rel": "payment"

    }

  ],

  "mode": "live",

  "eventName": "PAYMENT_PROCESSING"

}

Payment Completed

{

  "payload": {

    "accountId": "1002495240",

    "id": "7422f92f-fb13-4f51-bc00-86bee277a506",

    "merchantRefNum": "523a463c-c6a1-4e64-ace9-0c1161b9a31a",

    "paymentHandleToken": "PHC0uHklty7AIXEI",

    "amount": 500000,

    "currencyCode": "<currency>",

    "status": "COMPLETED",

    "gatewayResponse": {

      "operationId": "0123124567407707",

      "id": "b08562c0-9e7a-45e6-a8f2-17eaf669a38a",

      "processor": "SAFETYPAY",

      "status": "102"

    },

    "paymentType": "<paymentmethodname>",

    "source": "SingleAPI",

    "availableToSettle": 0,

    "txnTime": "2023-05-04T08:20:29Z",

    "customerIp": "213.208.158.212",

    "profile": {

      "email": "BRTESTQA202_01@gmail.com"

    },

    "settleWithAuth": true,

    "statusTime": "2023-05-04T08:28:21Z",

    "updatedTime": "2023-05-04T08:28:21Z",

    "gatewayReconciliationId": "b08562c0-9e7a-45e6-a8f2-17eaf669a38a"

  },

  "eventType": "PAYMENT_COMPLETED",

  "attemptNumber": "1",

  "resourceId": "7422f92f-fb13-4f51-bc00-86bee277a506",

  "eventDate": "2023-05-04T08:20:29Z",

  "links": [

    {

      "href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002495240/payments/7422f92f-fb13-4f51-bc00-86bee277a506",

      "rel": "payment"

    }

  ],

  "mode": "live",

  "eventName": "PAYMENT_COMPLETED"

}

Payment Failed

{

  "payload": {

    "accountId": "1002495260",

    "id": "49dacbaf-4246-416c-8335-4686656c048d",

    "merchantRefNum": "ff2f3b4c-89c4-4af1-bffe-4b980d8dfe10",

    "paymentHandleToken": "PHdCouX8GqXt68AR",

    "amount": 20000,

    "currencyCode": "<currency>",

    "status": "FAILED",

    "gatewayResponse": {

      "operationId": "0123124567275575",

      "id": "16b022a0-d8bf-46a2-8e91-e57917faa700",

      "processor": "SAFETYPAY",

      "status": "100"

    },

    "paymentType": "<paymentmethodname>",

    "availableToSettle": 0,

    "txnTime": "2023-05-04T05:41:46Z",

    "customerIp": "213.208.158.212",

    "profile": {

      "email": "CLKHIPU0212_01@gmail.com"

    },

    "settleWithAuth": true,

    "statusTime": "2023-05-04T06:02:21Z",

    "updatedTime": "2023-05-04T06:02:21Z",

    "gatewayReconciliationId": "16b022a0-d8bf-46a2-8e91-e57917faa700"

  },

  "eventType": "PAYMENT_FAILED",

  "attemptNumber": "1",

  "resourceId": "49dacbaf-4246-416c-8335-4686656c048d",

  "eventDate": "2023-05-04T05:41:46Z",

  "links": [

    {

      "href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002495260/payments/49dacbaf-4246-416c-8335-4686656c048d",

      "rel": "payment"

    }

  ],

  "mode": "live",

  "eventName": "PAYMENT_FAILED"

}

GET Calls

GET Payment Handle call with Payment Handle ID returned to the response of /paymentHandles call

https://api.test.paysafe.com:443/paymenthub/v1/paymenthandles/<Payment Handle ID>

GET Payment Handle call using Merchant reference number sent in the request of /paymentHandles call

https://api.test.paysafe.com:443/paymenthub/v1/paymenthandles?merchantRefNum=<merchantrefNum>

GET Payment Handle call with Payment Handle ID returned to the response of /payments call

https://api.test.paysafe.com:443/paymenthub/v1/payments/<Payment Handle ID>

GET Payment Handle call using Merchant reference number sent in the request of /payments call

https://api.test.paysafe.com:443/paymenthub/v1/payments?merchantRefNum=<merchantrefNum>

Was this page helpful?

On this Page

Webhooks
Sample Webhook Packets
Payment Handle Payable
Payment Handle Completed
Payment Handle Expired with "statusReason": "AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE"
Payment Handle Expired "statusReason": "AUTH_EXPIRED"
Payment Handle Error
Payment Processing
Payment Completed
Payment Failed
GET Calls

Search Overlay

Webhooks and GET calls

Was this page helpful?

Thank you for your response!