Settings

⚙️
Webhook URL settings
The target URL to which HTTP POST requests will be sent needs to be provided to your integration manager, and confirmation should be received that it has been added to the partner settings on Paybis end.

Available webhooks

Executed event

Webhook on the successfully executed event, after the crypto transaction is submitted to the blockchain.

Request

Parameter	Type	Description
`event_id`	REQUIRED uuid	Event id.
`transaction_id`	REQUIRED uuid	Transaction id. Paybis will return value from `payment.transaction.id` from the corresponding Event.
`invoice`	OPTIONAL string	Invoice reference associated with the transaction.
`status`	REQUIRED string	Status of the failed payout. Example: `Rejected`.
`reason`	OPTIONAL string	Explanation of why the payout failed.
`digital_amount_sent`	REQUIRED object
`digital_amount_sent.currency`	REQUIRED string	Cryptocurrency is sent to the crypto address.
`digital_amount_sent.amount`	REQUIRED string	Crypto amount sent to the crypto address.
`blockchain_txn_hash`	OPTIONAL string	The blockchain transaction hash.

{
  "event_id": "0000079f-6981-4cd7-bf7b-88c5699eebb5",
  "transaction_id": "26e312b9-2206-1005-227e-f95808946cd3",
  "digital_amount_sent": {
    "currency": "BTC",
    "amount": "0.699999"
  },
  "blockchain_txn_hash": "492e43fa04ec86d7d4bc7deb38e4956312e78eb68d97824e73660a52283344ab"
}

{
  "event_id": "4e882fc8-07d1-4759-bbc5-4c0d8029109d",
  "event_type": "TransactionCryptoPayoutError",
  "transaction_id": "785bae8a-759d-4eb3-b1c1-307f221018f1",
  "invoice": "PBQA240628300573TX2",
  "status": "Rejected",
  "amount_sent": {
    "amount": "1000",
    "currency": "BTC-TESTNET"
  },
  "reason": "some reason test 28.06",
  "timestamp": 1719293227
}

Failed transaction

Webhook is sent for the transaction that were created in the Paybis system but failed during processing.
Funds for these transactions will not be deducted from the prefunded balance.

Request

Parameter	Type	Description
`event_id`	REQUIRED uuid	Event id.
`transaction_id`	REQUIRED uuid	Transaction id. Paybis will return value from `payment.transaction.id` from the corresponding Event.
`event_type`	REQUIRED string	For failed transactions, the value will always be `TransactionRejected`.
`invoice`	REQUIRED string	The ID of the transaction in both the Paybissystem and the Partner Portal..

{
  "event_id": "8194cf8b-4d45-4086-b3e5-53b22269db75",
  "event_type": "TransactionRejected",
  "transaction_id": "596decb6-43e5-41c6-87f0-22d91771e11f",
  "invoice": "PBQA250711396021TX13"
}

Prefunded balance top-up

This webhook notifies the partner when a prefunded balance has been successfully credited to their account. It provides transaction details, sender information, and updated balance state to help partners reconcile funding events in near real time.

Payload Parameters

Parameter	Type	Description
`event_type`	REQUIRED `string`	Type of the event. Always `"PrefundedBalanceToppedUp"` for successful top-ups.
`amount`	`string`	Total amount credited to IBAN.
`fees`	`string`	Transaction fee debited from partner's account.
`net_amount`	`string`	Amount credited to the prefunded balance.
`currency`	`string`	Currency of the credited amount (e.g., `EUR`).
`transaction_type`	`string`	`"credit"` for top-up transactions.
`balance_before`	`string`	Balance before the top-up.
`balance_after`	`string`	Balance after the top-up.
`sender_name`	`string`	Name of the sender initiating the transfer (available for auto top-up only).
`sender_iban`	`string`	Sender’s IBAN (available for auto top-up only).
`payment_reference`	`string`	Reference message provided with the payment.

{
  "event": "PrefundedBalanceToppedUp",
  "time": "2025-07-21T08:35:59+00:00",
	"amount":"100.00",
	"fees":"2.50",
	"net_amount":"97.50",
  "currency": "EUR",
  "transaction_type": "credit",
  "balance_before": "100.00",
  "balance_after": "197.50",
  "sender_name": "Acme Inc",
  "sender_iban": "GR22SEOU19870010111222",
  "payment_reference": "Payment for inv. 123 as of 12.06.2025"
}

{
  "event": "PrefundedBalanceToppedUp",
  "time": "2025-07-21T08:35:59+00:00",
	"amount":"100.00",
	"fees":"2.50",
	"net_amount":"97.50",
  "currency": "EUR",
  "transaction_type": "credit",
  "balance_before": "100.00",
  "balance_after": "197.50",
  "payment_reference": "Payment for inv. 123 as of 12.06.2025"
}

Security

For your safety we sign each webhook message with the NIST P-256 (secp256r1) key using the SHA256withECDSA (ECDSA with SHA-256) asymmetric signing algo. The signature is encoded to base64 and sent with the original request in the X-Request-Signature header.

❗️
Important When verifying the signature, use the raw request body as the message, without any modifications or transformations. Treat the request body as a plain string of characters.

Use our public key to verify incoming POST calls.

Production public key:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEi+Op2heNAuGVOFjRiv9jB2eNva6p
vqCHARX5a0JGXDcZvrdX8KGfa/4uceMiJ0pTTVzMRFVSduIxKEisFz4D0w==
-----END PUBLIC KEY-----

Sandbox environment public key:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEYQi7GQ67Zb5EyWExUP5swcruMw3N
m+cKdzxHJE6Qeht8ze/ADfWdMy49Tee3ctWQRkf/+6Q358iFhxo8qpNKGg==
-----END PUBLIC KEY-----

Response

A successful HTTP response is expected (2xx code).