Webhooks
Deprecated: Please use the Webhook API for reference
If you want to receive notifications informing you of payment status updates, you need to create on your server an URL to receive and HTTP POST request from Paybyrd and configure it in your subscription.
Set up a Webhook setting
When your server is ready to handle the notifications, you need to set up your URL into your merchant account. To achieve this you need to call the following endpoint:
curl --location --request POST 'https://gateway.paybyrd.com/api/v2/webhooks' \
--header 'X-Api-Key: 0807af49-76c3-46ad-83c1-bf059b894e64' \
--header 'Content-Type: application/json' \
--data-raw '{
"url": "https://test-url.com/webhook"
}'
POST /api/v2/webhooks HTTP/1.1
Host: gateway.paybyrd.com
X-Api-Key: 0807af49-76c3-46ad-83c1-bf059b894e64
Content-Type: application/json
Content-Length: 47
{
"url": "https://test-url.com/webhook"
}
You can have multiple Webhook settings for the same subscription, but they must have different URL's.
See the full API reference here.
Retrieve data about Webhook settings
You can use Paybyrd Webhook API to query data about created Webhooks. To get information about created Webhook settings, you can make the following endpoint call:
curl --location --request GET 'https://gateway.paybyrd.com/api/v2/webhooks' \
--header 'X-Api-Key: 0807af49-76c3-46ad-83c1-bf059b894e64'
GET /api/v2/webhooks HTTP/1.1
Host: gateway.paybyrd.com
X-Api-Key: 0807af49-76c3-46ad-83c1-bf059b894e64
If you want to retrieve data from a specific Webhook setting, you can make a call to the same endpoint, by specifying the Webhook Id.
curl --location --request GET 'https://gateway.paybyrd.com/v2/webhooks/ec30eb47-c986-437e-9ff8-ded2dcd0a208' \
--header 'X-Api-Key: 0807af49-76c3-46ad-83c1-bf059b894e64'
GET /api/v2/webhooks/ec30eb47-c986-437e-9ff8-ded2dcd0a208 HTTP/1.1
Host: gateway.paybyrd.com
X-Api-Key: 0807af49-76c3-46ad-83c1-bf059b894e64
Webhook URL, user and password will be masked for security purposes.
Enabling and disabling a Webhook
You can not remove a Webhook setting for security purposes. But you can disable one by specifying its Webhook Id into a disable endpoint request. By doing that, the Webhook will not be called by Paybyrd to send notifications.
curl --location --request POST 'https://gateway.paybyrd.com/api/v2/webhooks/ec30eb47-c986-437e-9ff8-ded2dcd0a208/disable' \
--header 'X-Api-Key: 0807af49-76c3-46ad-83c1-bf059b894e64'
POST /api/v2/webhooks/ec30eb47-c986-437e-9ff8-ded2dcd0a208/disable HTTP/1.1
Host: gateway.paybyrd.com
X-Api-Key: 0807af49-76c3-46ad-83c1-bf059b894e64
If you want to enable a Webhook so it can again receive notifications, just do a similar call to the enable Webhook endpoint:
curl --location --request POST 'https://gateway.paybyrd.com/api/v2/webhooks/ec30eb47-c986-437e-9ff8-ded2dcd0a208/enable' \
--header 'X-Api-Key: 0807af49-76c3-46ad-83c1-bf059b894e64'
POST /api/v2/webhooks/ec30eb47-c986-437e-9ff8-ded2dcd0a208/enable HTTP/1.1
Host: gateway.paybyrd.com
X-Api-Key: 0807af49-76c3-46ad-83c1-bf059b894e64
Receive the hook from Paybyrd
In your server, you will receive a request from Paybyrd with the transactionId which the status has changed. We expect a HTTP success status response from your server, which can be 200 OK, 201 CREATED, 202 ACCEPTED, otherwise Paybyrd will consider that your server was not able to handle the notification. Paybyrd has a retry policy of 12 attempts.
This is a sample payload of the hook sent by us:
{
"webhookId": "1642449226",
"contextType": "event:paymentStatusChanged",
"paymentId": "96b5aa9b-aad8-442f-84bb-c327fdebe53e",
"transactionId": "96b5aa9b-aad8-442f-84bb-c327fdebe53e",
"orderId": "36a77bfe-7304-4977-8e41-93a88c6e93f3"
}
Once the hook is received, you may query the transaction in order to obtain detailed information about its status.
Updated about 1 year ago