Webhook API

This document provides information on webhooks for Paybyrd. Webhooks allow you to receive real-time notifications about various events related to orders, transactions, payments, and more.

The API url is:


To configure the webhook, authentication is required using an API Key. Include your API Key in the header of your HTTP request using the key x-api-key.


Include the following header in your HTTP request to authenticate the webhook:

x-api-key: Your-API-Key

Replace Your-API-Key with the actual API Key provided by Paybyrd.

This API Key ensures secure and authorized communication between your system and the PayByrd webhook endpoint. Keep your API Key confidential and do not share it publicly.


The endpoint URL for configuration is:


Below, we list various events that you can subscribe to for real-time notifications related to orders, transactions, and chargebacks.

If no events are specified in your configuration, Paybyrd will interpret it as a request to subscribe to all available events.


Order Creation and Status
order.createdIndicates when a new order is created in the system.
order.pendingThe order is awaiting further action or confirmation.
order.paidThe order has been fully paid.
order.refundedSome order amount has been refunded.
order.canceledThe order has been canceled.
order.expiredThe order has expired and is no longer valid.
order.temporaryfailedTemporary failure occurred during the order payment process.


transaction.preauth.pendingAwaiting approval for a preauthorization at the transaction level.
transaction.preauth.successThe preauthorization at the transaction level has been successfully approved.
transaction.preauth.failedThe transaction-level preauthorization process has failed.
transaction.preauth.errorAn error occurred during the transaction-level preauthorization.
transaction.preauth.canceledThe transaction-level preauthorization has been canceled.
transaction.capture.pendingAwaiting confirmation for capturing funds at the transaction level.
transaction.capture.successThe funds capture at the transaction level has been successfully completed.
transaction.capture.failedThe attempt to capture funds at the transaction level has failed.
transaction.capture.errorAn error occurred during the funds capture process at the transaction level.
transaction.capture.canceledThe funds capture process at the transaction level has been canceled.
transaction.payment.pendingAwaiting confirmation for the payment at the transaction level.
transaction.payment.successThe payment at the transaction level has been successfully processed.
transaction.payment.failedThe payment process at the transaction level has failed.
transaction.payment.errorAn error occurred during the payment process at the transaction level.
transaction.payment.canceledThe payment process at the transaction level has been canceled.
transaction.refund.pendingAwaiting confirmation for the refund at the transaction level.
transaction.refund.successThe refund at the transaction level has been successfully processed.
transaction.refund.failedThe refund process at the transaction level has failed.
transaction.refund.errorAn error occurred during the refund process at the transaction level.
transaction.refund.canceledThe refund process at the transaction level has been canceled.


Chargeback Lifecycle
chargeback.createdA chargeback has been initiated.
chargeback.disputingThe chargeback is in the process of being disputed.
chargeback.pendingactionPending further action regarding the chargeback.
chargeback.closedThe chargeback case has been closed.
chargeback.wonThe chargeback dispute has been won.
chargeback.lostThe chargeback dispute has been lost.

Payment methods

Paybyrd supports various payment methods for transactions. When configuring your webhook, you can specify one or more of the following payment methods.

If no payment methods are specified in your configuration, Paybyrd will interpret it as a request to subscribe to all available payment methods.

Available Payment Methods

Payment MethodDescription
cardCredit or debit card transactions.
idealiDEAL transactions, a popular online payment method in the Netherlands.
multibancoMultibanco transactions, a widely used payment method in Portugal.
mbwayMB WAY transactions, a mobile payment method in Portugal.
multicaixaMulticaixa transactions, commonly used in Angola.
pickupTransactions involving in-store or designated pickup.
paypalPayPal transactions, a globally recognized online payment platform.
banktransferStandard bank transfers.
floaTransactions involving Floa, a specific payment method.
pixTransactions involving Pix, a popular instant payment method in Brazil.

Webhook Authentication Credentials

When PayByrd sends requests to your specified webhook URL, it needs the appropriate credentials for secure and authorized communication. PayByrd supports two types of authentication credentials:

1. API Key

  • Type: api-key
  • Authentication Method: PayByrd includes an x-api-key in the request header.

To authenticate requests using an API Key, PayByrd adds a unique x-api-key to the request header. This acts as a secure identifier, allowing your webhook to verify the authenticity of incoming requests.

2. Basic Authentication

  • Type: basic
  • Authentication Method: PayByrd generates a username and password, sending them in basic authentication format.

For basic authentication, PayByrd generates a username and password combination. These credentials are sent in the request header using the basic authentication format, providing an additional layer of security.

How It works

  • When you configure your webhook, you choose the desired authentication method.
  • If you opt for an API Key, PayByrd generates an API key, sending it in the request header.
  • If you choose basic authentication, PayByrd generates a username and password, sending them securely in the request header.


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


Through the API, it's also possible to query the generated webhooks, check their status, review the responses obtained in each attempt, and even resend them if necessary.

The endpoint URL for webhooks is:


When querying data through the API, you can use the following parameter:


  • referenceId: This parameter accepts either an OrderId, TransactionId, or ChargebackId. It serves as the source identifier for the webhook data you wish to retrieve. This means that when making a query, you provide the specific OrderId, TransactionId, or ChargebackId related to the webhook data you are interested in. The referenceId parameter allows you to narrow down and target your query to obtain precise information based on the unique identifier you provide.


When working with a large dataset and needing to navigate through multiple pages of results, the API provides pagination support. To effectively iterate through these pages, utilize the following headers:

  • x-page: Specify the page number you want to retrieve.
  • x-page-size: Determine the length of each page.

If you set x-page to 2 and x-page-size to 10, you will receive results starting from the 11th record, allowing you to efficiently manage and retrieve the data in manageable chunks.

These headers enable you to control the flow of data retrieval, ensuring flexibility and efficiency when working with paginated API responses.

Webhook Response Ordering

To enhance clarity and convenience, our webhook responses are systematically ordered from the most recent to the oldest instances. This ordering principle ensures that when you review or retrieve webhook responses, you are presented with the latest data first.

Why Ordering Matters
  1. Visibility of Recent Activity:

    • The most recent responses appear at the top of the list, providing immediate visibility into the latest webhook interactions.
  2. Streamlined Analysis:

    • When analyzing webhook responses, the chronological ordering facilitates a more streamlined process, allowing you to focus on recent events before delving into historical data.
  3. Efficient Debugging:

    • For debugging purposes, starting with the most recent responses allows for quicker identification of recent issues or successes, expediting the troubleshooting process.

Understanding this ordering principle enhances your experience in working with webhook responses, promoting efficient analysis and decision-making based on the most up-to-date information.


curl --location 'https://webhook.paybyrd.com/api/v1/webhooks?referenceId=YourReferenceId' \
--header 'x-api-key: YourApiKey'
curl --location 'https://webhook.paybyrd.com/api/v1/webhooks' \
--header 'x-api-key: 7c051c9e-4506-4545-834f-af0d88863374' \
--header 'x-page-size: 25' \
--header 'x-page: 1'

Querying Webhook Attempts

After receiving a webhook, you may want to review all the attempts made for it. In such cases, you can access our attempts endpoint.

The endpoint URL for attempts is:

This endpoint allows you to retrieve detailed information about the various attempts made for a specific webhook.

Pagination for Attempts

When dealing with a substantial amount of data from multiple attempts, efficient navigation becomes essential. The API supports pagination to help you manage and retrieve this information systematically. To make the most of this feature, consider the following headers:

  • x-page: Specify the page number you wish to retrieve.
  • x-page-size: Determine the length of each page.


If you set x-page to 2 and x-page-size to 10, you will receive results starting from the 11th attempt record. This facilitates a more organized and manageable approach to reviewing multiple attempts associated with a webhook.

Webhook Resending

If the need arises, you can resend specific webhooks.

Endpoint URL for Resending Webhooks:

To resend webhooks, use the following curl command as an example:

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

This example demonstrates how to structure a curl request to the resend endpoint. Ensure to replace 'YourApiKey' with your actual API key and provide the relevant webhook IDs in the "ids" array.

This functionality enables you to manually trigger the resend process for specific webhooks as needed.

Webhook Data Retention Policy

Our webhook data is subject to different retention periods based on the outcome of the webhook processing. For cases of failure, we retain webhook information for up to one month, encompassing all attempts made, as well as the payloads sent and received.

In the case of successful webhooks, the data is available for a more limited duration of one week, starting from the creation timestamp.

Data Retention Explanation

  • Failure Cases:

    • Retention Period: Up to one month.
    • Details: Information includes all webhook attempts, along with the payloads sent and received during each attempt.
  • Success Cases:

    • Retention Period: One week from the creation timestamp.
    • Details: Data is available for a more concise period, focusing on successful webhook instances.

Purge Routine Explanation

The routine of purging involves systematically removing webhook data that has surpassed its designated retention period. This process ensures that our data storage remains efficient, holding only the relevant information for the specified duration.

Understanding this retention policy helps users comprehend how long they can access webhook data and the circumstances that determine its availability. If there are specific data retrieval needs beyond these periods, alternative measures or queries to the API may be necessary.

Software Development Kit (SDK)

.Net (C#)

We offer a .NET SDK available on Nuget, and it's open source for the community on GitHub. This SDK simplifies integration, providing pre-built functionalities for easier development. If you prefer not to integrate manually, the SDK is a convenient option.