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

Crypto Payouts

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.
`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.
`fees`	REQUIRED object	Breakdown of the fees applied to the transaction. Initial fees are based on the quote; final fees are taken from the executed transaction (the transaction is the source of truth), so values may be updated in subsequent webhooks.
`fees.currency`	REQUIRED string	Currency in which all fee amounts are expressed (e.g. `EUR`).
`fees.network_fee`	REQUIRED string	Blockchain network fee.
`fees.service_fee`	REQUIRED string	Paybis service fee.
`fees.partner_fee`	REQUIRED string	Partner fee (your markup).
`fees.total_fee`	REQUIRED string	Sum of all fees: `network_fee` + `service_fee` + `partner_fee`.

{
  "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",
  "fees": {
  "network_fee": { "currency": "EUR", "amount": "0.95" },
  "service_fee": { "currency": "EUR", "amount": "0.47" },
  "partner_fee": { "currency": "EUR", "amount": "0.33" },
  "total_fee":   { "currency": "EUR", "amount": "1.75" }
  }
}

{
  "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 Paybis system and the Partner Portal.

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

Crypto Payins

Transaction Status Lifecycle

Every Pay-in transaction moves through a defined set of statuses.

Status	Description
`in_progress`	The transaction has been successfully created and an internal ID assigned.
`waiting_for_funds`	The unique deposit address is active, and the system is monitoring the blockchain for the user's deposit.
`deposit_confirmed`	A valid blockchain transaction has been detected and has reached the required number of confirmations. The exchange rate is locked.
`completed`	The crypto has been successfully sold, and the fiat equivalent has been credited to your prefunded balance.
`failed`	The transaction was rejected (e.g., AML risk, slippage error) or timed out. Funds are not credited.

Request

Parameter	Type	Description
`event_id`	REQUIRED uuid	Unique event identifier provided during creation.
`id`	REQUIRED string	Paybis internal transaction ID.
`event_type`	REQUIRED string	The type of event. Always `PayIn` for deposit events.
`status`	REQUIRED string	Current status of the transaction (e.g., `deposit_confirmed`, `completed`).
`blockchain_address`	REQUIRED string	The specific crypto deposit address generated for this transaction.
`crypto`	REQUIRED object	Object containing the `amount` and `currency` of the cryptocurrency received.
`fiat`	REQUIRED object	Object containing the `amount` and `currency` of the fiat credited to the ledger.
`rate`	REQUIRED string	The exchange rate applied to the conversion.
`fees`	REQUIRED object	Breakdown of the fees applied to the transaction, expressed in fiat. Initial values are based on the quote; final values are set once the transaction is executed (the transaction is the source of truth). Final fee values are delivered with the `completed` status.
`fees.currency`	REQUIRED string	Currency in which all fee amounts are expressed (e.g. `EUR`).
`fees.network_fee`	REQUIRED string	Blockchain network fee.
`fees.service_fee`	REQUIRED string	Paybis service fee.
`fees.partner_fee`	REQUIRED string	Partner fee (your markup).
`fees.total_fee`	REQUIRED string	Sum of all fees: `network_fee` + `service_fee` + `partner_fee`.

Payload

{
  "timestamp": 1720609400,
  "event_type": "PayIn",
  "event_id": "2c3ae520-97b5-4e2c-995e-48f9b59f9f95",
  "id": "tx-88392010",
  "status": "deposit_confirmed",
  "blockchain_address": "bc1q6v5tpkkpqu5r6gwvpa9xh3atnpyvw2cs9talpp",
  "rate": "82408.12",
  "crypto": {
    "amount": "0.02154870",
    "currency": "BTC"
  },
  "fiat": {
    "amount": "1344.82",
    "currency": "EUR"
  },
  "fees": {
    "network_fee": { "currency": "EUR", "amount": "0.95" },
    "service_fee": { "currency": "EUR", "amount": "0.47" },
    "partner_fee": { "currency": "EUR", "amount": "0.33" },
    "total_fee":   { "currency": "EUR", "amount": "1.75" }
  }
}

{
  "timestamp": 1720609100,
  "event_type": "PayIn",
  "event_id": "1f2ae520-97b5-4e2c-995e-48f9b59f9f95",
  "id": "tx-88392010",
  "status": "waiting_for_funds",
  "blockchain_address": "bc1q6v5tpkkpqu5r6gwvpa9xh3atnpyvw2cs9talpp",
  "rate": "82408.12",
  "crypto": {
    "amount": "0.02154870",
    "currency": "BTC"
  },
  "fiat": {
    "amount": "1344.82",
    "currency": "EUR"
  },
  "fees": {
    "currency": "EUR",
    "network_fee": "0.00",
    "service_fee": "2.07",
    "partner_fee": "1.05",
    "total_fee": "3.12"
  }
}

{
  "timestamp": 1720609800,
  "event_type": "PayIn",
  "event_id": "3d4ae520-97b5-4e2c-995e-48f9b59f9f95",
  "id": "tx-88392010",
  "status": "completed",
  "blockchain_address": "bc1q6v5tpkkpqu5r6gwvpa9xh3atnpyvw2cs9talpp",
  "rate": "82408.12",
  "crypto": {
    "amount": "0.02154870",
    "currency": "BTC"
  },
  "fiat": {
    "amount": "1344.82",
    "currency": "EUR"
  },
  "fees": {
    "currency": "EUR",
    "network_fee": "0.00",
    "service_fee": "2.07",
    "partner_fee": "1.05",
    "total_fee": "3.12"
  }
}

📘
Note

The deposit address is generated asynchronously, so blockchain_address may not yet be available in the in_progress webhook.

The completed webhook carries the final fee values. Use these amounts for reconciliation.

Fiat Payouts

Webhook sent whenever a fiat payout's status changes. Every status transition uses the same payload structure and event_type (Payout) - the status field carries the current state.

Transaction Status Lifecycle

Every Fiat Payout transaction moves through a defined set of statuses.

Status	Description
`in_progress`	The payout has been created. The OpenPayd API has been called, the partner webhook has been sent, and the database has been updated.
`in_transit`	Funds have been transferred and are currently in the OpenPayd system. The partner webhook has been sent and the database has been updated.
`completed`	The beneficiary has received the funds. The partner webhook has been sent, the database has been updated, and the transaction is closed.
`failed`	The transaction was rejected or could not be processed. Funds are not deducted from the prefunded balance.

Successful Transaction

Webhook is sent when the fiat payout has been successfully delivered to the beneficiary bank account.

Request

Parameter	Type	Description
`event_type`	REQUIRED string	Always `Payout`.
`event_id`	REQUIRED uuid	Unique identifier of this webhook event.
`id`	REQUIRED uuid	Paybis internal transaction id. Value from `payment.transaction.id` of the corresponding Event.
`status`	REQUIRED string	Current payout status: `in_progress`, `in_transit`, `completed`, or `failed`.
`reference`	REQUIRED string	Payment reference provided in the payout request.
`timestamp`	REQUIRED integer	Event time as a Unix epoch (seconds).
`amount`	REQUIRED object	Payout amount sent to the beneficiary.
`amount.amount`	REQUIRED string	Payout amount.
`amount.currency`	REQUIRED string	Currency of the payout (e.g. `EUR`).
`commission`	REQUIRED object	Commission charged on the payout, deducted from the prefunded balance.
`commission.amount`	REQUIRED string	Commission amount.
`commission.currency`	REQUIRED string	Commission currency (e.g. `EUR`).
`beneficiary`	REQUIRED object	Details of the payment recipient.
`beneficiary.type`	REQUIRED string	`business` or `individual`.
`beneficiary.iban`	REQUIRED string	Beneficiary IBAN.
`beneficiary.companyName`	CONDITIONAL string	Present when `type` = `business`.
`beneficiary.firstName`	CONDITIONAL string	Present when `type` = `individual`.
`beneficiary.lastName`	CONDITIONAL string	Present when `type` = `individual`.
`failure_reason`	CONDITIONAL string	Present only when `status` = `failed`. Reason the payout failed.

{
  "event_type": "Payout",
  "timestamp": 1791204617,
  "event_id": "97fae698-5101-4aab-be0f-e7f8db0e2630",
  "id": "28ca178c-12d7-4577-b1ad-2462b4fe2f97",
  "status": "completed",
  "reference": "Invoice 2026-09",
  "beneficiary": {
    "companyName": "ACME GmbH",
    "iban": "DE89370400440532013000",
    "type": "business"
  },
  "commission": {
    "amount": "18.53",
    "currency": "EUR"
  },
  "amount": {
    "amount": "37059.00",
    "currency": "EUR"
  }
}

{
  "event_type": "Payout",
  "timestamp": 1791201000,
  "event_id": "c33c3b43-fa0c-44fe-a37d-63567167cbe7",
  "id": "94e4e4d5-c271-42d1-b2ab-cdc64074ac80",
  "status": "in_transit",
  "reference": "Invoice 12345",
  "beneficiary": {
    "iban": "ES7921000813610123456789",
    "type": "individual"
  },
  "amount": {
    "amount": "20.00",
    "currency": "EUR"
  }
}

Failed Transaction

Sent when a payout fails during processing. Funds are not deducted from the prefunded balance. It is the same Payout event with status = failed and an added optional failure_reason.

Request

Parameter	Type	Description
`event_type`	REQUIRED string	Always `Payout`.
`event_id`	REQUIRED uuid	Unique identifier of this webhook event.
`id`	REQUIRED uuid	Paybis internal transaction id. Value from `payment.transaction.id` of the corresponding Event.
`status`	REQUIRED string	Always `failed`.
`reference`	REQUIRED string	Payment reference provided in the payout request.
`timestamp`	REQUIRED integer	Event time as a Unix epoch (seconds).
`amount`	REQUIRED object	Payout amount that was requested.
`amount.amount`	REQUIRED string	Payout amount.
`amount.currency`	REQUIRED string	Currency of the payout (e.g. `EUR`).
`beneficiary`	REQUIRED object	Details of the payment recipient.
`beneficiary.type`	REQUIRED string	`business` or `individual`.
`beneficiary.iban`	REQUIRED string	Beneficiary IBAN.
`beneficiary.companyName`	CONDITIONAL string	Present when `type` = `business`.
`beneficiary.firstName`	CONDITIONAL string	Present when `type` = `individual`.
`beneficiary.lastName`	CONDITIONAL string	Present when `type` = `individual`.
`failure_reason`	OPTIONAL string	Free-text reason the payout failed, provided by Paybis or the payment provider. Not a fixed list of codes.

{
  "event_type": "Payout",
  "timestamp": 1791204290,
  "event_id": "2dd4e169-af06-4587-b3ad-40147729ebe4",
  "id": "abadbff4-d47e-41b0-b17f-debcb17205e1",
  "status": "failed",
  "reference": "Invoice 12345",
  "beneficiary": {
    "iban": "ES7921000813610123456789",
    "type": "individual"
  },
  "amount": {
    "amount": "20.00",
    "currency": "EUR"
  },
  "failure_reason": "Failed create payout"
}

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 `

❗️
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).

Retry policy

The HTTP 2xx responses indicate that our webhook call was successful. If your server returns a 5xx response, we retry up to 48 times. The retries are made sequentially, one after another, without a delay between the attempts. Each delivery attempt has a response timeout of 15 sec. Responses other than 2xx and 5xx (for example, 4xx) are not retried.