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 by providing a valid gift card number and PIN. |
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 the Openbucks page. However, the consumer either abandoned the transaction or failed to authorize it. |
EXPIRED | - | The payment handle has expired because it was not used in the payments call within 15 minutes (TTL). |
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>
Example webhook packets for payments
{
"payload": {
"accountId": "1002349865",
"id": "852124f7-8a19-427d-ba43-dedfda5aa670",
"merchantRefNum": "b49f11b4-44b8-4c4d-aaaa-1e195173c68e",
"paymentHandleToken": "PH7ZBzKtPoKXGQPe",
"transactionType": "PAYMENT",
"amount": 10,
"currencyCode": "USD",
"status": "PROCESSING",
"paymentType": "GIFTCARDS",
"billingDetails": {
"street1": "100 Queen",
"street2": "Unit 201",
"zip": "123456",
"city": "Toronto",
"country": "US"
},
"statusTime": "2025-07-16T10:03:47Z",
"updatedTime": "2025-07-16T10:03:47Z",
"gatewayReconciliationId": "4d6e3279-b2af-4896-bdf5-8116b350dfaf",
"customerIp": "172.0.0.1",
"profile": {
"firstName": "kranthi",
"lastName": "kumar",
"email": "test@paysafe.com",
"dateOfBirth": {
"day": 1,
"month": 1,
"year": 1901
},
"phone": "1234567890"
},
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"merchantDescriptor": {
"dynamicDescriptor": "OnlineStore",
"phone": "12345678"
},
"gatewayResponse": {
"processor": "SKRILL_QCO",
"sid": "6ee0cfa302a5cf34939465861125b4d4"
},
"txnTime": "2025-07-16T10:01:31Z"
},
"eventType": "PAYMENT_HANDLE_PROCESSING",
"attemptNumber": "1",
"resourceId": "852124f7-8a19-427d-ba43-dedfda5aa670",
"eventDate": "2025-07-16T10:01:31Z",
"links": [
{
"href": "https://api.qa.paysafe.com/alternatepayments/v1/accounts/1002349865/paymenthandles/852124f7-8a19-427d-ba43-dedfda5aa670",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_PROCESSING"
}
{
"payload": {
"accountId": "1002349865",
"id": "852124f7-8a19-427d-ba43-dedfda5aa670",
"merchantRefNum": "b49f11b4-44b8-4c4d-aaaa-1e195173c68e",
"paymentHandleToken": "PH7ZBzKtPoKXGQPe",
"transactionType": "PAYMENT",
"amount": 10,
"currencyCode": "USD",
"status": "PAYABLE",
"paymentType": "GIFTCARDS",
"billingDetails": {
"street1": "100 Queen",
"street2": "Unit 201",
"zip": "123456",
"city": "Toronto",
"country": "US"
},
"statusTime": "2025-07-16T10:11:47Z",
"updatedTime": "2025-07-16T10:11:47Z",
"gatewayReconciliationId": "4d6e3279-b2af-4896-bdf5-8116b350dfaf",
"customerIp": "172.0.0.1",
"profile": {
"firstName": "kranthi",
"lastName": "kumar",
"email": "test@paysafe.com",
"dateOfBirth": {
"day": 1,
"month": 1,
"year": 1901
},
"phone": "1234567890"
},
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"merchantDescriptor": {
"dynamicDescriptor": "OnlineStore",
"phone": "12345678"
},
"gatewayResponse": {
"transaction_id": "4d6e3279-b2af-4896-bdf5-8116b350dfaf",
"amount": "0.10",
"mb_transaction_id": "378941962",
"pay_from_email": "test@paysafe.com",
"pay_to_email": "georgizgeorgiev.mer.us@sun-fish.com",
"currency": "USD",
"merchant_id": "313447233",
"id": "378941962",
"processor": "SKRILL_QCO",
"status": "2",
"sid": "6ee0cfa302a5cf34939465861125b4d4"
},
"txnTime": "2025-07-16T10:01:31Z"
},
"eventType": "PAYMENT_HANDLE_PAYABLE",
"attemptNumber": "1",
"resourceId": "852124f7-8a19-427d-ba43-dedfda5aa670",
"eventDate": "2025-07-16T10:01:31Z",
"links": [
{
"href": "https://api.qa.paysafe.com/alternatepayments/v1/accounts/1002349865/paymenthandles/852124f7-8a19-427d-ba43-dedfda5aa670",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_PAYABLE"
}
{
"payload": {
"accountId": "1002983610",
"id": "e16181ef-b315-474b-9aa8-8e334344c482",
"merchantRefNum": "a15d95d1-f8af-4715-95fd-9954099e081c",
"paymentHandleToken": "PHQRWKT2PileKgkP",
"transactionType": "PAYMENT",
"amount": 100,
"currencyCode": "USD",
"status": "COMPLETED",
"paymentType": "GIFTCARDS",
"billingDetails": {
"country": "US"
},
"statusTime": "2025-07-21T07:08:20Z",
"updatedTime": "2025-07-21T07:08:20Z",
"gatewayReconciliationId": "c890d05b-e4e1-43b6-b0eb-b43dd546a34e",
"customerIp": "115.114.129.142",
"profile": {
"firstName": "ALBERTA",
"lastName": "BOBBETHCHARLESON",
"email": "ivankapaunova.austria@sun-fish.com"
},
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"gatewayResponse": {
"transaction_id": "c890d05b-e4e1-43b6-b0eb-b43dd546a34e",
"amount": "1.0",
"merchant_id": "-1187919625",
"payerIban": "e8a5420c6a5646eda2ed4cb7920176ef",
"processor": "SKRILL_QCO",
"sid": "8557b34e67e942acaae04b9c5b214ac2",
"mb_transaction_id": "441635460",
"pay_from_email": "fake@email.com",
"pay_to_email": "georgizgeorgiev.mer.us@sun-fish.com",
"payerName": "ALBERTA BOBBETHCHARLESON",
"currency": "USD",
"id": "441635460",
"status": "2"
},
"txnTime": "2025-07-21T07:07:16Z"
},
"eventType": "PAYMENT_HANDLE_COMPLETED",
"attemptNumber": "1",
"resourceId": "e16181ef-b315-474b-9aa8-8e334344c482",
"eventDate": "2025-07-21T07:07:16Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002983610/paymenthandles/e16181ef-b315-474b-9aa8-8e334344c482",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_COMPLETED"
}
{ "payload": {
"accountId": "1002983610",
"id": "cd766cd4-b444-408c-b197-d4c9872e84eb",
"merchantRefNum": "921e1f7f-48b1-47f9-b475-9278ef36ddb5",
"paymentHandleToken": "PHYUFcdvCqYHI03m",
"transactionType": "PAYMENT",
"amount": 100,
"currencyCode": "USD",
"status": "FAILED",
"paymentType": "GIFTCARDS",
"billingDetails": {
"country": "US"
},
"statusTime": "2025-07-21T07:11:53Z",
"updatedTime": "2025-07-21T07:11:53Z",
"gatewayReconciliationId": "280f6907-cdeb-463d-85c0-33464abcb8b2",
"customerIp": "115.114.129.142",
"profile": {
"firstName": "ALBERTA",
"lastName": "BOBBETHCHARLESON",
"email": "ivankapaunova.austria@sun-fish.com"
},
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"gatewayResponse": {
"transaction_id": "280f6907-cdeb-463d-85c0-33464abcb8b2",
"amount": "1.0",
"merchant_id": "-1187919625",
"payerIban": "85c41739cc5143228e569a81228bb9eb",
"processor": "SKRILL_QCO",
"sid": "0ba4d724866449a885d0fed1663b1abf",
"mb_transaction_id": "39397675",
"pay_from_email": "fake@email.com",
"pay_to_email": "georgizgeorgiev.mer.us@sun-fish.com",
"payerName": "ALBERTA BOBBETHCHARLESON",
"currency": "USD",
"id": "39397675",
"status": "-2"
},
"txnTime": "2025-07-21T07:11:42Z",
"error": {
"code": "1001",
"message": "External Gateway Error",
"details": [
"An external gateway error occurred."
]
}
},
"eventType": "PAYMENT_HANDLE_FAILED",
"attemptNumber": "1",
"resourceId": "cd766cd4-b444-408c-b197-d4c9872e84eb",
"eventDate": "2025-07-21T07:11:42Z",
"links": [
{
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1002983610/paymenthandles/cd766cd4-b444-408c-b197-d4c9872e84eb",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_FAILED"
}
{"payload": {
"accountId": "1002349865",
"id": "852124f7-8a19-427d-ba43-dedfda5aa670",
"merchantRefNum": "b49f11b4-44b8-4c4d-aaaa-1e195173c68e",
"paymentHandleToken": "PH7ZBzKtPoKXGQPe",
"transactionType": "PAYMENT",
"amount": 10,
"currencyCode": "USD",
"status": "EXPIRED",
"statusReason": "AUTH_EXPIRED",
"paymentType": "GIFTCARDS",
"billingDetails": {
"street1": "100 Queen",
"street2": "Unit 201",
"zip": "123456",
"city": "Toronto",
"country": "US"
},
"statusTime": "2025-07-16T10:24:18Z",
"updatedTime": "2025-07-16T10:24:18Z",
"gatewayReconciliationId": "4d6e3279-b2af-4896-bdf5-8116b350dfaf",
"customerIp": "172.0.0.1",
"profile": {
"firstName": "kranthi",
"lastName": "kumar",
"email": "test@paysafe.com",
"dateOfBirth": {
"day": 1,
"month": 1,
"year": 1901
},
"phone": "1234567890"
},
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"merchantDescriptor": {
"dynamicDescriptor": "OnlineStore",
"phone": "12345678"
},
"gatewayResponse": {
"transaction_id": "4d6e3279-b2af-4896-bdf5-8116b350dfaf",
"failed_reason_code": "Cannot login: The email or password you have entered has expired or does not match our records. Please try again or follow our password retrieval procedure.",
"amount": "0.10",
"mb_transaction_id": "378941962",
"pay_from_email": "test@paysafe.com",
"pay_to_email": "georgizgeorgiev.mer.us@sun-fish.com",
"currency": "USD",
"merchant_id": "313447233",
"id": "378941962",
"processor": "SKRILL_QCO",
"sid": "6ee0cfa302a5cf34939465861125b4d4"
},
"txnTime": "2025-07-16T10:01:31Z",
"error": {
"code": "1001",
"message": "External Gateway Error",
"details": [
"An external gateway error occurred.",
"Cannot login: The email or password you have entered has expired or does not match our records. Please try again or follow our password retrieval procedure."
]
}
},
"eventType": "PAYMENT_HANDLE_EXPIRED",
"attemptNumber": "1",
"resourceId": "852124f7-8a19-427d-ba43-dedfda5aa670",
"eventDate": "2025-07-16T10:01:31Z",
"links": [
{
"href": "https://api.qa.paysafe.com/alternatepayments/v1/accounts/1002349865/paymenthandles/852124f7-8a19-427d-ba43-dedfda5aa670",
"rel": "payment_handle"
}
],
"mode": "live",
"eventName": "PAYMENT_HANDLE_EXPIRED"
}
{
"payload": {
"accountId": "1002349865",
"id": "daf92486-c75b-4e53-9dbc-db81d51f21c2",
"merchantRefNum": "b49f11b4-44b8-4c4d-aaaa-1e195173c68e",
"paymentHandleToken": "PH7ZBzKtPoKXGQPe",
"amount": 10,
"currencyCode": "USD",
"status": "COMPLETED",
"gatewayResponse": {
"transaction_id": "4d6e3279-b2af-4896-bdf5-8116b350dfaf",
"failed_reason_code": "Cannot login: The email or password you have entered has expired or does not match our records. Please try again or follow our password retrieval procedure.",
"amount": "0.10",
"mb_transaction_id": "378941962",
"pay_from_email": "test@paysafe.com",
"pay_to_email": "georgizgeorgiev.mer.us@sun-fish.com",
"currency": "USD",
"merchant_id": "313447233",
"id": "378941962",
"processor": "SKRILL_QCO",
"sid": "6ee0cfa302a5cf34939465861125b4d4"
},
"statusReason": "AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE",
"paymentType": "GIFTCARDS",
"availableToSettle": 0,
"txnTime": "2025-07-16T10:01:31Z",
"error": {
"code": "1001",
"message": "External Gateway Error",
"details": [
"An external gateway error occurred."
]
},
"billingDetails": {
"street1": "100 Queen",
"street2": "Unit 201",
"zip": "123456",
"city": "Toronto",
"country": "US"
},
"customerIp": "172.0.0.1",
"profile": {
"firstName": "kranthi",
"lastName": "kumar",
"email": "test@paysafe.com",
"dateOfBirth": {
"day": 1,
"month": 1,
"year": 1901
},
"phone": "1234567890"
},
"settleWithAuth": true,
"statusTime": "2025-07-16T10:24:22Z",
"updatedTime": "2025-07-16T10:24:22Z",
"gatewayReconciliationId": "4d6e3279-b2af-4896-bdf5-8116b350dfaf"
},
"eventType": "PAYMENT_COMPLETED",
"attemptNumber": "1",
"resourceId": "daf92486-c75b-4e53-9dbc-db81d51f21c2",
"eventDate": "2025-07-16T10:01:31Z",
"links": [
{
"href": "https://api.qa.paysafe.com/alternatepayments/v1/accounts/1002349865/payments/daf92486-c75b-4e53-9dbc-db81d51f21c2",
"rel": "payment"
}
],
"mode": "live",
"eventName": "PAYMENT_COMPLETED"
}
Was this page helpful?
On this Page