Webhooks
You receive a webhook when the payment handle status or payment status changes. You can also look up the status by executing a GET payment handle or GET payment call.
| Payment handle status | Payment status | Event |
|---|---|---|
PROCESSING | - | The consumer has been redirected to the redirection link. |
PAYABLE | - | The consumer successfully authorized the transaction using the online bank you redirected them to. |
COMPLETED | COMPLETED | You initiated the payments call and the transaction was successful. |
COMPLETED | FAILED | You initiated the payments call and the transaction failed. NOTE: Regardless of the payments call response status, the payment handle status always changes to COMPLETED when a payments call is made. |
FAILED | - | The payment handle was created, and the consumer was redirected to their bank. However, the consumer failed to authorize it. |
EXPIRED | - | The payment handle has expired because it was not used in the payments call within 15 minutes (TTL). |
| ERROR | - | Payment handle could not be created. |
Example webhook packets for payments
{
"payload": {
"accountId": "1002786770",
"id": "4e32ba5d-1c87-47fb-871a-b972cf8fd19e",
"merchantRefNum": "b9358763-c4e6-4a9e-92f6-c93b78d2db44",
"paymentHandleToken": "PHPTRF98fcZLo6ve",
"transactionType": "PAYMENT",
"amount": 300,
"currencyCode": "EUR",
"status": "PROCESSING",
"paymentType": "EPS",
"statusTime": "2025-03-24T15:31:49Z",
"updatedTime": "2025-03-24T15:31:49Z",
"gatewayReconciliationId": "f7dca956-b7c6-43ad-a719-68e037cf9f73",
"customerIp": "213.161.69.211",
"profile": {
"firstName": "Ivanka",
"lastName": "Paunova",
"email": "joe.sweet@paysafe.com"
},
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"gatewayResponse": {
"processor": "SKRILL_QCO",
"sid": "6524005fbe764b40b732c699d9e0cb59"
},
"txnTime": "2025-03-24T15:31:11Z"
},
"eventType": "PAYMENT_HANDLE_PROCESSING",
"attemptNumber": "1",
"resourceId": "4e32ba5d-1c87-47fb-871a-b972cf8fd19e",
"eventDate": "2025-03-24T15:31:11Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/paymenthandles/4e32ba5d-1c87-47fb-871a-b972cf8fd19e",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_PROCESSING"
}
{
"payload": {
"accountId": "1002786770",
"id": "4e32ba5d-1c87-47fb-871a-b972cf8fd19e",
"merchantRefNum": "b9358763-c4e6-4a9e-92f6-c93b78d2db44",
"paymentHandleToken": "PHPTRF98fcZLo6ve",
"transactionType": "PAYMENT",
"amount": 300,
"currencyCode": "EUR",
"status": "PAYABLE",
"paymentType": "EPS",
"statusTime": "2025-03-24T15:42:59Z",
"updatedTime": "2025-03-24T15:42:59Z",
"gatewayReconciliationId": "f7dca956-b7c6-43ad-a719-68e037cf9f73",
"customerIp": "213.161.69.211",
"profile": {
"firstName": "Ivanka",
"lastName": "Paunova",
"email": "joe.sweet@paysafe.com"
},
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"gatewayResponse": {
"transaction_id": "f7dca956-b7c6-43ad-a719-68e037cf9f73",
"amount": "3.0",
"mb_transaction_id": "237775350",
"pay_from_email": "joe.sweet@paysafe.com",
"pay_to_email": "paysafe-product@outlook.com",
"currency": "EUR",
"merchant_id": "-903749737",
"id": "237775350",
"processor": "SKRILL_QCO",
"status": "2",
"sid": "6524005fbe764b40b732c699d9e0cb59"
},
"txnTime": "2025-03-24T15:31:11Z"
},
"eventType": "PAYMENT_HANDLE_PAYABLE",
"attemptNumber": "1",
"resourceId": "4e32ba5d-1c87-47fb-871a-b972cf8fd19e",
"eventDate": "2025-03-24T15:31:11Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/paymenthandles/4e32ba5d-1c87-47fb-871a-b972cf8fd19e",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_PAYABLE"
}
{
"payload": {
"accountId": "1002786770",
"id": "4e32ba5d-1c87-47fb-871a-b972cf8fd19e",
"merchantRefNum": "b9358763-c4e6-4a9e-92f6-c93b78d2db44",
"paymentHandleToken": "PHPTRF98fcZLo6ve",
"transactionType": "PAYMENT",
"amount": 300,
"currencyCode": "EUR",
"status": "COMPLETED",
"paymentType": "EPS",
"statusTime": "2025-03-24T15:44:05Z",
"updatedTime": "2025-03-24T15:44:05Z",
"gatewayReconciliationId": "f7dca956-b7c6-43ad-a719-68e037cf9f73",
"customerIp": "213.161.69.211",
"profile": {
"firstName": "Ivanka",
"lastName": "Paunova",
"email": "joe.sweet@paysafe.com"
},
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"gatewayResponse": {
"transaction_id": "f7dca956-b7c6-43ad-a719-68e037cf9f73",
"amount": "3.0",
"mb_transaction_id": "237775350",
"pay_from_email": "joe.sweet@paysafe.com",
"pay_to_email": "paysafe-product@outlook.com",
"currency": "EUR",
"merchant_id": "-903749737",
"id": "237775350",
"processor": "SKRILL_QCO",
"status": "2",
"sid": "6524005fbe764b40b732c699d9e0cb59"
},
"txnTime": "2025-03-24T15:31:11Z"
},
"eventType": "PAYMENT_HANDLE_COMPLETED",
"attemptNumber": "1",
"resourceId": "4e32ba5d-1c87-47fb-871a-b972cf8fd19e",
"eventDate": "2025-03-24T15:31:11Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/paymenthandles/4e32ba5d-1c87-47fb-871a-b972cf8fd19e",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_COMPLETED"
}
{
"payload": {
"accountId": "1002786770",
"id": "e55fce91-af08-46a6-939e-94687574bb51",
"merchantRefNum": "96135a4b-7e84-4c6c-995d-888ef069b499",
"paymentHandleToken": "PHYODyPEyFerqGvW",
"transactionType": "PAYMENT",
"amount": 300,
"currencyCode": "EUR",
"status": "FAILED",
"paymentType": "EPS",
"statusTime": "2025-03-24T13:39:40Z",
"updatedTime": "2025-03-24T13:39:40Z",
"gatewayReconciliationId": "15636cde-f9c4-4666-99ec-4750e2fc32dd",
"customerIp": "213.161.69.211",
"profile": {
"firstName": "Ivanka",
"lastName": "Paunova",
"email": "joe.sweet@paysafe.com"
},
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"gatewayResponse": {
"transaction_id": "15636cde-f9c4-4666-99ec-4750e2fc32dd",
"amount": "3.0",
"mb_transaction_id": "1940713467",
"pay_from_email": "joe.sweet@paysafe.com",
"pay_to_email": "paysafe-product@outlook.com",
"currency": "EUR",
"merchant_id": "-903749737",
"id": "1940713467",
"processor": "SKRILL_QCO",
"status": "-2",
"sid": "beea9f25edbe41c9870de69f5ff06dee"
},
"txnTime": "2025-03-24T13:39:16Z",
"error": {
"code": "1001",
"message": "External Gateway Error",
"details": [
"An external gateway error occurred."
]
}
},
"eventType": "PAYMENT_HANDLE_FAILED",
"attemptNumber": "1",
"resourceId": "e55fce91-af08-46a6-939e-94687574bb51",
"eventDate": "2025-03-24T13:39:16Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/paymenthandles/e55fce91-af08-46a6-939e-94687574bb51",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_FAILED"
}
{
"payload": {
"accountId": "1002786770",
"id": "3d81e4d7-6235-447e-a30a-b8990e0e94d5",
"merchantRefNum": "d855ee69-99e1-4776-9451-5e6e64878e1c",
"paymentHandleToken": "PHJwXqjyIqdifClM",
"transactionType": "PAYMENT",
"amount": 300,
"currencyCode": "EUR",
"status": "EXPIRED",
"statusReason": "AUTH_EXPIRED",
"paymentType": "EPS",
"billingDetails": {
"street1": "100 Queen Street West",
"street2": "stree 2",
"zip": "M5H 2N2",
"city": "Toronto",
"country": "NL",
"state": "CA"
},
"statusTime": "2025-03-21T13:26:00Z",
"updatedTime": "2025-03-21T13:26:00Z",
"gatewayReconciliationId": "00bcb367-bf67-449a-a7de-a1dbe50816b0",
"customerIp": "213.161.69.211",
"profile": {
"firstName": "Ivanka",
"lastName": "Paunova",
"email": "joe.sweet@paysafe.com",
"dateOfBirth": {
"day": 26,
"month": 10,
"year": 1991
}
},
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"gatewayResponse": {
"transaction_id": "00bcb367-bf67-449a-a7de-a1dbe50816b0",
"amount": "3.00",
"mb_transaction_id": "6121825116",
"pay_from_email": "joe.sweet@paysafe.com",
"pay_to_email": "paysafe-product@outlook.com",
"currency": "EUR",
"merchant_id": "221270472",
"id": "6121825116",
"processor": "SKRILL_QCO",
"status": "2",
"sid": "d47fe79719d9ba5c69215ae58d7d5275"
},
"txnTime": "2025-03-21T11:40:14Z"
},
"eventType": "PAYMENT_HANDLE_EXPIRED",
"attemptNumber": "1",
"resourceId": "3d81e4d7-6235-447e-a30a-b8990e0e94d5",
"eventDate": "2025-03-21T11:40:14Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/paymenthandles/3d81e4d7-6235-447e-a30a-b8990e0e94d5",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_EXPIRED"
}
{
"payload": {
"accountId": "1002786770",
"id": "fa139eda-2fd8-4e67-a6bb-627089713514",
"merchantRefNum": "e6a05559-b120-4de1-bacc-f20c224d2549",
"transactionType": "PAYMENT",
"amount": 300,
"currencyCode": "EUR",
"status": "ERROR",
"paymentType": "EPS",
"statusTime": "2025-03-24T12:49:54Z",
"updatedTime": "2025-03-24T12:49:54Z",
"customerIp": "213.161.69.211",
"txnTime": "2025-03-24T12:49:54Z",
"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.,profile.firstName:size must be between 1 and 80 where leading and trailing spaces are omitted"
]
}
},
"eventType": "PAYMENT_HANDLE_ERRORED",
"attemptNumber": "1",
"resourceId": "fa139eda-2fd8-4e67-a6bb-627089713514",
"eventDate": "2025-03-24T12:49:54Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/paymenthandles/fa139eda-2fd8-4e67-a6bb-627089713514",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_ERRORED",
"EventName": "PAYMENT_HANDLE_ERRORED"
}
{
"payload": {
"accountId": "1002786770",
"id": "26eb2b3b-05ca-461c-8f05-abbe41935978",
"merchantRefNum": "854ff860-4409-42e3-bea7-aec9a8bcab97",
"paymentHandleToken": "PHPTRF98fcZLo6ve",
"amount": 300,
"currencyCode": "EUR",
"status": "COMPLETED",
"gatewayResponse": {
"transaction_id": "f7dca956-b7c6-43ad-a719-68e037cf9f73",
"amount": "3.0",
"mb_transaction_id": "237775350",
"pay_from_email": "joe.sweet@paysafe.com",
"pay_to_email": "paysafe-product@outlook.com",
"currency": "EUR",
"merchant_id": "-903749737",
"id": "237775350",
"processor": "SKRILL_QCO",
"status": "2",
"sid": "6524005fbe764b40b732c699d9e0cb59"
},
"paymentType": "EPS",
"source": "SingleAPI",
"availableToSettle": 0,
"txnTime": "2025-03-24T15:31:11Z",
"customerIp": "213.161.69.211",
"profile": {
"firstName": "Ivanka",
"lastName": "Paunova",
"email": "joe.sweet@paysafe.com"
},
"settleWithAuth": true,
"statusTime": "2025-03-24T15:44:05Z",
"updatedTime": "2025-03-24T15:44:05Z",
"gatewayReconciliationId": "f7dca956-b7c6-43ad-a719-68e037cf9f73"
},
"eventType": "PAYMENT_COMPLETED",
"attemptNumber": "1",
"resourceId": "26eb2b3b-05ca-461c-8f05-abbe41935978",
"eventDate": "2025-03-24T15:31:11Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/payments/26eb2b3b-05ca-461c-8f05-abbe41935978",
"rel": "payment"
}
],
"mode": "live",
"eventName": "PAYMENT_COMPLETED"
}
Example webhook packets for payouts
{
"payload": {
"accountId": "1002786770",
"id": "78f1f6e9-424a-4248-84b0-cbaa89d166e8",
"merchantRefNum": "64a9058f-c849-4984-82b5-36ae276cc243",
"paymentHandleToken": "PHBkEhmsPCAl6EuD",
"transactionType": "STANDALONE_CREDIT",
"amount": 451,
"currencyCode": "EUR",
"status": "PAYABLE",
"paymentType": "EPS",
"statusTime": "2025-03-24T13:01:22Z",
"updatedTime": "2025-03-24T13:01:22Z",
"gatewayReconciliationId": "b5238073-a932-4ecc-8b9b-d5e5b4f41f46",
"customerIp": "213.161.69.211",
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"gatewayResponse": {
"processor": "SKRILL_QCO"
},
"txnTime": "2025-03-24T13:01:22Z"
},
"eventType": "PAYMENT_HANDLE_PAYABLE",
"attemptNumber": "1",
"resourceId": "78f1f6e9-424a-4248-84b0-cbaa89d166e8",
"eventDate": "2025-03-24T13:01:22Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/paymenthandles/78f1f6e9-424a-4248-84b0-cbaa89d166e8",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_PAYABLE"
}
{
"payload": {
"accountId": "1002786770",
"id": "1911dc82-5a5b-410e-89c4-3a15b01926f4",
"merchantRefNum": "4117c446-bda5-431d-b688-f84bb30d7f65",
"paymentHandleToken": "PHiUj0rYGSVJtECL",
"transactionType": "STANDALONE_CREDIT",
"amount": 451,
"currencyCode": "EUR",
"status": "COMPLETED",
"paymentType": "EPS",
"statusTime": "2025-03-24T13:04:06Z",
"updatedTime": "2025-03-24T13:04:06Z",
"gatewayReconciliationId": "710c353a-3e53-4ed7-b3ff-b03aa6d0b9c2",
"customerIp": "213.161.69.211",
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"gatewayResponse": {
"processor": "SKRILL_QCO"
},
"txnTime": "2025-03-24T13:03:53Z"
},
"eventType": "PAYMENT_HANDLE_COMPLETED",
"attemptNumber": "1",
"resourceId": "1911dc82-5a5b-410e-89c4-3a15b01926f4",
"eventDate": "2025-03-24T13:03:53Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/paymenthandles/1911dc82-5a5b-410e-89c4-3a15b01926f4",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_COMPLETED"
}
{
"payload": {
"accountId": "1002786770",
"id": "b33071c0-56cb-424f-905a-923054d0bad3",
"merchantRefNum": "e4da635f-24c5-4c34-bf5a-513fd5a33691",
"paymentHandleToken": "PHGcjWzRbHo3sf6z",
"amount": 451,
"currencyCode": "EUR",
"status": "PENDING",
"paymentType": "EPS",
"txnTime": "2025-03-24T13:06:21Z",
"customerIp": "213.161.69.211",
"gatewayResponse": {
"mb_amount": "5",
"mb_currency": "EUR",
"pay_from_email": "paysafe-product@outlook.com",
"id": "835714141",
"merchant_id": "555555",
"processor": "SKRILL_QCO",
"sid": "4072156ba7264963b183a364b1d264b5",
"status": "1"
},
"statusTime": "2025-03-24T13:06:21Z",
"updatedTime": "2025-03-24T13:06:21Z",
"gatewayReconciliationId": "AQAAABFTPA"
},
"eventType": "SA_CREDIT_PENDING",
"attemptNumber": "1",
"resourceId": "b33071c0-56cb-424f-905a-923054d0bad3",
"eventDate": "2025-03-24T13:06:21Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/standalonecredits/b33071c0-56cb-424f-905a-923054d0bad3",
"rel": "standalone_credit"
}
],
"mode": "live",
"eventName": "SA_CREDIT_PENDING"
}
{
"payload": {
"accountId": "1002786770",
"id": "6a239102-fa8d-4a4e-a67a-d6194154de5d",
"merchantRefNum": "186c0c9e-d8a7-4bec-a507-b6b576a13925",
"paymentHandleToken": "PHiUj0rYGSVJtECL",
"amount": 451,
"currencyCode": "EUR",
"status": "ERROR",
"statusReason": "PSP_REJECTED",
"paymentType": "EPS",
"txnTime": "2025-03-24T13:04:04Z",
"customerIp": "213.161.69.211",
"gatewayResponse": {
"processor": "SKRILL_QCO",
"error_msg": "GENERIC_ERROR",
"sid": "463b7a56bdb6b3cb7ced530236eaef73"
},
"statusTime": "2025-03-24T13:04:06Z",
"updatedTime": "2025-03-24T13:04:06Z",
"gatewayReconciliationId": "AQAAABFTO4"
},
"eventType": "SA_CREDIT_ERRORED",
"attemptNumber": "1",
"resourceId": "6a239102-fa8d-4a4e-a67a-d6194154de5d",
"eventDate": "2025-03-24T13:04:04Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/standalonecredits/6a239102-fa8d-4a4e-a67a-d6194154de5d",
"rel": "standalone_credit"
}
],
"mode": "live",
"eventName": "SA_CREDIT_ERRORED"
}
Example webhook packets for refunds
{
"payload": {
"accountId": "1002786770",
"id": "b95b73ec-4604-4558-bb14-a1bf448e8eb1",
"merchantRefNum": "d2fa6658-b0e0-465b-9347-61bb1c10691d",
"amount": 200,
"currencyCode": "EUR",
"source": "SingleAPI",
"status": "COMPLETED",
"paymentType": "EPS",
"txnTime": "2025-03-24T13:10:11Z"
},
"eventType": "REFUND_COMPLETED",
"attemptNumber": "1",
"resourceId": "b95b73ec-4604-4558-bb14-a1bf448e8eb1",
"eventDate": "2025-03-24T13:10:11Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/refunds/b95b73ec-4604-4558-bb14-a1bf448e8eb1",
"rel": "refund"
}
],
"mode": "live",
"eventName": "REFUND_COMPLETED"
}
{
"payload": {
"accountId": "1002786770",
"id": "6f2a3317-af01-4aac-a0c9-0fc9999376ec",
"merchantRefNum": "a23daa0a-adbf-4bd5-9da6-5a32ca9dbe1a",
"amount": 1122,
"currencyCode": "EUR",
"source": "SingleAPI",
"status": "FAILED",
"paymentType": "EPS",
"txnTime": "2025-03-24T13:05:05Z",
"error": {
"code": "ALTERNATE-PAYMENTS-GATEWAY-6",
"message": "Over refund",
"details": [
"The total refund amount cannot exceed the original payment amount."
]
}
},
"eventType": "REFUND_FAILED",
"attemptNumber": "1",
"resourceId": "6f2a3317-af01-4aac-a0c9-0fc9999376ec",
"eventDate": "2025-03-24T13:05:05Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/refunds/6f2a3317-af01-4aac-a0c9-0fc9999376ec",
"rel": "refund"
}
],
"mode": "live",
"eventName": "REFUND_FAILED"
}
{
"payload": {
"accountId": "1002786770",
"id": "388a039c-7dd1-49f3-a70c-10a3be4dfc1e",
"merchantRefNum": "e1361fc1-2340-47b7-983e-532bc1b5abba",
"amount": 200,
"currencyCode": "EUR",
"source": "SingleAPI",
"status": "ERROR",
"paymentType": "EPS",
"txnTime": "2025-03-24T13:05:15Z",
"error": {
"code": "1001",
"message": "External Gateway Error",
"details": [
"An external gateway error occurred.",
"GENERIC_ERROR"
]
}
},
"eventType": "REFUND_ERRORED",
"attemptNumber": "1",
"resourceId": "388a039c-7dd1-49f3-a70c-10a3be4dfc1e",
"eventDate": "2025-03-24T13:05:15Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002786770/refunds/388a039c-7dd1-49f3-a70c-10a3be4dfc1e",
"rel": "refund"
}
],
"mode": "live",
"eventName": "REFUND_ERRORED"
}
GET calls
Use the following GET calls to look up the payment handle or payment status:
- GET payment handle using the payment handle ID returned in the response to your original /paymenthandles call.
Test: https://api.test.paysafe.com:443/paymenthub/v1/paymenthandles/<paymentHandleId>
Production: https://api.paysafe.com:443/paymenthub/v1/paymenthandles/<paymentHandleId>
- GET payment handle using the merchant reference number returned in the response to your original /paymenthandles call.
Test: https://api.test.paysafe.com:443/paymenthub/v1/paymenthandles?merchantRefNum=<merchantrefNum>
Production: https://api.paysafe.com:443/paymenthub/v1/paymenthandles?merchantRefNum=<merchantrefNum>
- GET payment using the payment ID returned in the response to your original /payments call.
Test: https://api.test.paysafe.com:443/paymenthub/v1/payments/<paymentId>
Production: https://api.paysafe.com:443/paymenthub/v1/payments/<paymentId>
- GET payment using the merchant reference number returned in the response to your original /payments call.
Test: https://api.test.paysafe.com:443/paymenthub/v1/payments?merchantRefNum=<merchantrefNum>
Production: https://api.paysafe.com:443/paymenthub/v1/payments?merchantRefNum=<merchantrefNum>