Webhook API

Webhooks deliver real-time notifications about events related to orders, transactions, and chargebacks. Base URL: https://webhook.paybyrd.com

Authentication

Authenticate all requests with your API key in the x-api-key request header.

Settings

Configure webhook subscriptions at https://webhook.paybyrd.com/api/v1/settings.

Events

If no events are specified, Paybyrd subscribes to all available events.

Orders

Event	Description
order.created	A new order was created.
order.pending	The order is awaiting further action or confirmation.
order.paid	The order has been fully paid.
order.refunded	The order amount was refunded.
order.canceled	The order was canceled.
order.expired	The order expired without a completed payment.
order.temporaryfailed	A temporary failure occurred during the order payment process.

Transactions

Pre-authorisation

Event	Description
transaction.preauth.pending	Pre-authorisation is awaiting approval.
transaction.preauth.success	Pre-authorisation was approved.
transaction.preauth.failed	Pre-authorisation failed.
transaction.preauth.error	An error occurred during pre-authorisation.
transaction.preauth.canceled	Pre-authorisation was canceled.

Capture

Event	Description
transaction.capture.pending	Capture is awaiting confirmation.
transaction.capture.success	Capture completed successfully.
transaction.capture.failed	Capture failed.
transaction.capture.error	An error occurred during capture.
transaction.capture.canceled	Capture was canceled.

Payment

Event	Description
transaction.payment.pending	Payment is awaiting confirmation.
transaction.payment.success	Payment completed successfully.
transaction.payment.failed	Payment failed.
transaction.payment.error	An error occurred during payment.
transaction.payment.canceled	Payment was canceled.

Refund

Event	Description
transaction.refund.pending	Refund is awaiting confirmation.
transaction.refund.success	Refund completed successfully.
transaction.refund.failed	Refund failed.
transaction.refund.error	An error occurred during refund.
transaction.refund.canceled	Refund was canceled.

Chargebacks

Event	Description
chargeback.created	A chargeback was initiated.
chargeback.disputing	The chargeback is being disputed.
chargeback.pendingaction	The chargeback requires further action.
chargeback.closed	The chargeback case was closed.
chargeback.won	The chargeback dispute was won.
chargeback.lost	The chargeback dispute was lost.

Payment methods

If no payment methods are specified, Paybyrd subscribes to all available payment methods.

Payment method	Description
card	Credit or debit card transactions.
ideal	iDEAL transactions (Netherlands).
multibanco	Multibanco transactions (Portugal).
mbway	MB WAY transactions (Portugal).
multicaixa	Multicaixa transactions (Angola).
pickup	In-store or designated pickup transactions.
paypal	PayPal transactions.
banktransfer	Bank transfers.
floa	Floa transactions.
pix	Pix instant payment transactions (Brazil).

Webhook authentication

When Paybyrd sends requests to your webhook URL, it authenticates them using one of two credential types:

Type	Value	How it works
API Key	`api-key`	Paybyrd adds an `x-api-key` header to each request.
Basic	`basic`	Paybyrd generates a username and password sent in the `Authorization` header using Basic authentication format.

You select the credential type when creating the webhook configuration.

Managing configurations

Create a configuration:

curl --location 'https://webhook.paybyrd.com/api/v1/settings' \
--header 'x-api-key: {your_api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "url": "<YourWebhookURL>",
    "credentialType": "<DesiredCredentialType>",
    "events": [
        "...events you want to subscribe to"
    ],
    "paymentMethods": [
        "...payment methods you want to subscribe to"
    ]
}'

List configurations:

curl --location 'https://webhook.paybyrd.com/api/v1/settings' \
--header 'x-api-key: {your_api_key}'

Delete a configuration:

curl --location --request DELETE 'https://webhook.paybyrd.com/api/v1/settings/<WebhookSettingsId>' \
--header 'x-api-key: {your_api_key}'

Querying webhooks

Query generated webhooks, check their status, review attempt responses, and resend them at https://webhook.paybyrd.com/api/v1/webhooks.

Parameters

referenceId: An orderId, transactionId, or chargebackId. Filters results to webhooks associated with that entity.

Pagination

Use the following request headers to paginate results:

x-page: Page number to retrieve.
x-page-size: Number of results per page.

Results are ordered from most recent to oldest.

Examples

Query by referenceId:

curl --location 'https://webhook.paybyrd.com/api/v1/webhooks?referenceId=<YourReferenceId>' \
--header 'x-api-key: {your_api_key}'

Query with pagination:

curl --location 'https://webhook.paybyrd.com/api/v1/webhooks' \
--header 'x-api-key: {your_api_key}' \
--header 'x-page-size: 25' \
--header 'x-page: 1'

Retry behaviour

The webhook engine retries failed deliveries automatically. Any HTTP response outside the 2xx range is treated as a failure and triggers a retry.

Up to 50 retry attempts per webhook.
Retry intervals follow an arithmetic progression: the first retry is 1 minute after the failed attempt, increasing by 1 minute per retry, up to a maximum delay of 1 hour.

Querying attempts

Retrieve the attempt history for a specific webhook: GET https://webhook.paybyrd.com/api/v1/webhooks/{webhookId}/attempts Pagination is supported using the same x-page and x-page-size headers described above.

Resending webhooks

Manually resend one or more webhooks:

curl --location 'https://webhook.paybyrd.com/api/v1/webhooks/resend' \
--header 'x-api-key: {your_api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "ids": [
        "...webhook IDs to resend"
    ]
}'

Data retention

Outcome	Retention period
Failed webhooks	Up to 1 month (all attempts, payloads sent and received)
Successful webhooks	1 week from creation timestamp

SDK

A .NET SDK is available on NuGet and open source on GitHub.

API introduction

API reference

Authentication

Settings

Events

Orders

Transactions

Chargebacks

Payment methods

Webhook authentication

Managing configurations

Querying webhooks

Parameters

Examples

Retry behaviour

Querying attempts

Resending webhooks

Data retention

SDK

​Authentication

​Settings

​Events

​Orders

​Transactions

​Chargebacks

​Payment methods

​Webhook authentication

​Managing configurations

​Querying webhooks

​Parameters

​Pagination

​Examples

​Retry behaviour

​Querying attempts

​Resending webhooks

​Data retention

​SDK

Authentication

Settings

Events

Orders

Transactions

Chargebacks

Payment methods

Webhook authentication

Managing configurations

Querying webhooks

Parameters

Pagination

Examples

Retry behaviour

Querying attempts

Resending webhooks

Data retention

SDK