Enable Webhooks to Receive Application Statuses
Webhooks allow you to be informed automatically when the status of the merchant application you are onboarding changes.
This is not an Account Management API request. You must configure webhooks in the Paysafe Merchant Back Office to enable this service.
To configure webhooks:
- Sign in to the Merchant Back Office.
- Go to Settings > Notifications.
- Make sure the Account Status tab is selected.
- Select the Account Status Updates check box.
- In the Endpoint field, enter the URL to which you want callbacks sent.
- Click the Save button.
- It is important you make a note of the HMAC Secret Key which is located just below the Endpoint field. This signature is used to verify the authenticity of the webhook notification and confirm that none of the data is modified.
Once this has been configured, you will receive callbacks when the status of a merchant account that you have on-boarded has been changed – for example, from Deferred to Enabled (see Webhooks Statuses below for a list of possible account statuses). For example, you would receive the following notification if the status of the merchant account you created was changed to Enabled.
{
"id": "6a275b7c-6f11-4ed1-ae77-21071724574a",
"resourceId": "1003296300",
"mode": "live",
"eventDate": "2016-09-21T15:02:23Z",
"eventType": "ACCT_ENABLED",
"attemptNumber": 0,
"payload": {
"partnerId": 1000,
"acctStatus": "Enabled",
"accountNumber": "1003296300"
},
"links": [
{
"rel": "accounts",
"href": "https://api.test.paysafe.com/accountmanagement/v1/accounts/1003296300"
}
]
}
Notification Elements
| Element | Child Element | Required | Type | Description |
|---|---|---|---|---|
| id | Required | String Max = 36 | This is the unique ID of this request. | |
| resourceId | Required | String Max = 255 | This is the resource (account number) whose status is being updated. | |
| mode | Required | String | This indicates whether this is a live or test event. Possible values are:
| |
| eventDate | Required | dateTime | This is the date and time of the event (e.g., account status update). E.g., 2017-01-26T10:32:28Z | |
| eventType | Required | String Max = 255 | This is the type of callback event. | |
| payload | Required | |||
| partnerId | Required | String | This is partner ID assigned to you by Paysafe. | |
| acctStatus | Required | String | This is the current status of the merchant account you are onboarding with Paysafe. | |
| accountNumber | Required | String Max = 36 | This is the merchant account number you are onboarding with Paysafe. | |
| externalAccountId | Optional | String Max = 36 | This is an optional external account ID that may be assigned by the partner. | |
| links | Required | |||
| rel | Required | String | This is the link type that allows different endpoints to be targeted depending on the end state of the transaction. | |
| href | Required | String | This is the URI of the resource. | |
Some Notes on Webhooks
- All endpoint URLs need to be secure with HTTPS/SSL to ensure security.
- When the status of one of your merchant applications changes, Paysafe immediately sends a callback to your webhooks endpoint URL to inform you of the status change.
- To acknowledge the receipt of a webhook, Paysafe expects to get an HTTP status of 200 from your endpoint. In case we receive any other HTTP status code, we will assume that the webhooks has not been received by you and will attempt to resend it at a later time.
- If the callback for that account status change event fails (i.e., Paysafe does not get an acknowledgment of receipt with an HTTP Status Code of 200), Paysafe will make a maximum of 10 additional attempts to send a callback to that URL until successfully received – twice daily for 5 days.
- If the status of a different merchant application changes, and you are using the same webhooks URL for which some webhooks had failed, Paysafe will still make an initial callback attempt, and then 10 additional retries for that merchant account status change as well. (In other words, Paysafe does not disable callbacks to a URL in the event that it fails for one merchant account.) This is to ensure that notifications continue to be sent for subsequent events (i.e., other merchant applications) in case of a temporary issue with your endpoint.
- Because Paysafe does not have a notification method to alert you when callbacks are not reaching your endpoint URL, you should make sure to test your webhooks setup and the
Webhooks Statuses
Paysafe sends a webhook notification when the status of the merchant account is changed to any of the following:
| Status | Description | eventType |
|---|---|---|
| Approved | The merchant account has been approved, but not yet enabled. | ACCT_APPROVED |
| Deferred | The merchant account application has been deferred until underwriting by Risk/Compliance is completed. | ACCT_DEFERRED |
| Disabled | The merchant account application has been disabled due to suspension or termination. | ACCT_DISABLED |
| Enabled | The merchant account has been enabled for payment processing. | ACCT_ENABLED |
| Pending | The merchant account application has not yet been completed. | ACCT_PENDING |
| Processing | The merchant account application is being processed by Risk/Compliance. | ACCT_PROCESSING |
| Rejected | The merchant account application has been rejected due to Risk/Compliance check failure. | ACCT_REJECTED |
| Returned | The merchant account application has been returned from Risk to Compliance for review. | ACCT_RETURNED |
| Submitted | The merchant account has been submitted for review by Risk/Compliance. | ACCT_SUBMITTED |
| Waiting | Compliance is waiting for additional information to be provided by the merchant. | ACCT_WAITING |
| Withdrawn | The merchant account application has been withdrawn. | ACCT_WITHDRAWN |
Testing Webhooks
Because you will use the same callback URL for multiple merchant accounts, it is important to test the URL to establish that the webhooks URL functions properly. To test the webhooks service, once you have configured your callback URL, click the Test connectivity button.
Paysafe will immediately send a test callback with content similar to the following example.
{
"mode": "test",
"eventDate": "2017-11-17T16:21:01Z",
"eventType": "test",
"attemptNumber": 1
}
In order to accurately compute the Signature calculation, the HMACkey from Back-office has to be Base64 DECODED before any operation (binary – UTF8)”.