Overview

Webhooks are HTTPS POST requests that EukaPay sends to a URL you specify, notifying you in real-time about events in your account.

Create a Webhook

You can add your webhook endpoints in EukaPay Settings > Integrations > Webhooks.

Webhook Retry Policy

If a delivery fails, EukaPay will retry every 20 minutes for up to 2 hours before removing the event from the retry queue.

To check whether an event reached your endpoint, and to see the outcome of each delivery attempt, use the Webhook Events endpoint.

Event Types

The types of webhooks we send depend on the configured settings.

Event Type	Description
paymentCompleted	When a payment is made and the sum of payments for the invoice matches the requested amount.
paymentUnderpaid	When a payment is made, but the sum of payments for the invoice is less than the requested amount.
paymentOverpaid	When a payment is made, but the sum of payments for the invoice exceeds the requested amount.
paymentActionRequired	When a payment is held because compliance review needs more information from you before the funds can be released.
paymentInReview	When a payment is held while it is under compliance review. No action is required from you.
balanceCredited	When a payment held for compliance review is approved and the funds are credited to your balance. Sent to endpoints subscribed to paymentCompleted.
refundCompleted	When a refund has been successfully processed.
cryptoPayoutCreated	When a crypto payout request is created with the specified recipient details, payout amounts, and network information.
cryptoPayoutSent	When a crypto payout has been successfully processed and broadcast to the blockchain network.
cryptoPayoutError	When an error occurs during the creation or processing of a crypto payout.
cryptoPayoutRevoked	When a previously created crypto payout request is canceled before it is processed or sent.

N.B. The requested amount takes into account your transaction tolerances settings.

Payload

paymentCompleted

This webhook is sent when a payment is completed.

Attribute	Description
webhookId	This id uniquely identifies an event.
event	Webhook event type.
paymentCode	Unique code to identify the payment.
paidAmount	Amount in fiat currency associated with the payment.
totalPaidAmount	Sum of payments in fiat currency for the invoice.
status	Status of the invoice.
paidDatetime	Time the payment was made.
invoiceCode	Unique code to identify the invoice.
invoiceNumber	Unique number to identify the invoice, relative to your account.
invoicedAmount	Requested amount specified in the invoice for the products or services.
invoiceCurrency	Fiat currency which the invoice is issued and payments are to be made.
settlementNetAmount	Net amount credited to your balance for this payment, after fees, in `settlementCurrency`. `null` when it cannot be determined.
settlementCurrency	Currency `settlementNetAmount` is credited in: your settlement currency for fiat settlement (e.g. `CAD`), or the received cryptocurrency for crypto settlement (e.g. `USDT`). Can differ from `invoiceCurrency`. `null` when it cannot be determined.

settlementNetAmount and settlementCurrency are always present together. They are null (never 0 or omitted) when the net amount cannot be determined — for example, when an event is resent for a payment made before these fields were introduced.

Example paymentCompleted webhook payload:

{
  "webhookId": "ad82aaf3-9944-4022-a1e5-2518c33db67b",
  "event": "paymentCompleted",
  "paymentCode": "pym_d36p8sd5wina08tbfikx9xgu8n",
  "paidAmount": 3000,
  "totalPaidAmount": 3000,
  "status": "Paid",
  "paidDatetime": "2023-09-15T20:16:03.128Z",
  "invoiceCode": "inv_ozqtnhhavpgcyas32qxnlgkykx",
  "invoiceNumber": "718B4F26-1",
  "invoicedAmount": 3000,
  "invoiceCurrency": "USD",
  "settlementNetAmount": 2970,
  "settlementCurrency": "USD"
}

paymentActionRequired

This webhook is sent when a payment is held because compliance review needs more information before the funds can be released.

The payer has paid, but the funds are not yet credited to your balance. Once the review is resolved and the funds are released, a balanceCredited event follows.

Attribute	Description
webhookId	This id uniquely identifies an event.
event	Webhook event type.
paymentCode	Unique code to identify the payment.
paidAmount	Amount in fiat currency associated with the payment.
totalPaidAmount	Sum of payments in fiat currency for the invoice.
status	Status of the invoice.
paidDatetime	Time the payment was made.
invoiceCode	Unique code to identify the invoice.
invoiceNumber	Unique number to identify the invoice, relative to your account.
invoicedAmount	Requested amount specified in the invoice for the products or services.
invoiceCurrency	Fiat currency which the invoice is issued and payments are to be made.

Example paymentActionRequired webhook payload:

{
  "webhookId": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "event": "paymentActionRequired",
  "paymentCode": "pym_d36p8sd5wina08tbfikx9xgu8n",
  "paidAmount": 3000,
  "totalPaidAmount": 3000,
  "status": "Action Required",
  "paidDatetime": "2026-09-15T20:16:03.128Z",
  "invoiceCode": "inv_ozqtnhhavpgcyas32qxnlgkykx",
  "invoiceNumber": "718B4F26-1",
  "invoicedAmount": 3000,
  "invoiceCurrency": "USD"
}

paymentInReview

This webhook is sent when a payment is held while it is under compliance review. No action is required from you.

As with paymentActionRequired, the payer has paid but the funds are not yet credited to your balance. Once the review clears and the funds are released, a balanceCredited event follows.

Attribute	Description
webhookId	This id uniquely identifies an event.
event	Webhook event type.
paymentCode	Unique code to identify the payment.
paidAmount	Amount in fiat currency associated with the payment.
totalPaidAmount	Sum of payments in fiat currency for the invoice.
status	Status of the invoice.
paidDatetime	Time the payment was made.
invoiceCode	Unique code to identify the invoice.
invoiceNumber	Unique number to identify the invoice, relative to your account.
invoicedAmount	Requested amount specified in the invoice for the products or services.
invoiceCurrency	Fiat currency which the invoice is issued and payments are to be made.

Example paymentInReview webhook payload:

{
  "webhookId": "c2a3b4d5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "event": "paymentInReview",
  "paymentCode": "pym_d36p8sd5wina08tbfikx9xgu8n",
  "paidAmount": 3000,
  "totalPaidAmount": 3000,
  "status": "In Review",
  "paidDatetime": "2026-09-15T20:16:03.128Z",
  "invoiceCode": "inv_ozqtnhhavpgcyas32qxnlgkykx",
  "invoiceNumber": "718B4F26-1",
  "invoicedAmount": 3000,
  "invoiceCurrency": "USD"
}

balanceCredited

This webhook is sent when a payment that was held for compliance review is approved and the funds are credited to your balance.

For most payments, confirmation and crediting happen at the same moment and only paymentCompleted is sent. When a payment is held for compliance review the two are separate: paymentCompleted tells you the payer has paid, and balanceCredited tells you the funds are available. You do not subscribe to this event separately — endpoints subscribed to paymentCompleted receive it automatically.

Attribute	Description
webhookId	This id uniquely identifies an event.
event	Webhook event type.
paymentCode	Unique code to identify the payment.
creditedAmount	Amount credited for this payment, in `invoiceCurrency`. Same basis as `paidAmount` on paymentCompleted.
status	Status of the invoice.
creditedDatetime	Time the funds were credited to your balance.
invoiceCode	Unique code to identify the invoice.
invoiceNumber	Unique number to identify the invoice, relative to your account.
invoicedAmount	Requested amount specified in the invoice for the products or services.
invoiceCurrency	Fiat currency which the invoice is issued and payments are to be made.

Example balanceCredited webhook payload:

{
  "webhookId": "ad82aaf3-9944-4022-a1e5-2518c33db67b",
  "event": "balanceCredited",
  "paymentCode": "pym_d36p8sd5wina08tbfikx9xgu8n",
  "creditedAmount": 3000,
  "status": "Paid",
  "creditedDatetime": "2026-09-18T09:30:00.000Z",
  "invoiceCode": "inv_ozqtnhhavpgcyas32qxnlgkykx",
  "invoiceNumber": "718B4F26-1",
  "invoicedAmount": 3000,
  "invoiceCurrency": "USD"
}

paymentUnderpaid

This webhook is sent when a payment is underpaid.

Attribute	Description
webhookId	This id uniquely identifies an event.
event	Webhook event type.
paymentCode	Unique code to identify the payment.
paidAmount	Amount in fiat currency associated with the payment.
totalPaidAmount	Sum of payments in fiat currency for the invoice.
status	Status of the invoice.
paidDatetime	Time the payment was made.
invoiceCode	Unique code to identify the invoice.
invoiceNumber	Unique number to identify the invoice, relative to your account.
invoicedAmount	Requested amount specified in the invoice for the products or services.
invoiceCurrency	Fiat currency which the invoice is issued and payments are to be made.
settlementNetAmount	Net amount credited to your balance for this payment, after fees, in `settlementCurrency`. `null` when it cannot be determined.
settlementCurrency	Currency `settlementNetAmount` is credited in: your settlement currency for fiat settlement (e.g. `CAD`), or the received cryptocurrency for crypto settlement (e.g. `USDT`). Can differ from `invoiceCurrency`. `null` when it cannot be determined.

Example paymentUnderpaid webhook payload:

{
  "webhookId": "ad66aaf3-9944-4022-a1e5-2518c33db67b",
  "event": "paymentUnderpaid",
  "paymentCode": "pym_p9l9sd5wina08tbfikx9xgu8n",
  "paidAmount": 500,
  "totalPaidAmount": 1000,
  "status": "Underpaid",
  "paidDatetime": "2023-09-15T20:35:03.128Z",
  "invoiceCode": "inv_ozqtnhhavpgcyas32qxnlgkykx",
  "invoiceNumber": "718B4F26-1",
  "invoicedAmount": 3000,
  "invoiceCurrency": "USD",
  "settlementNetAmount": 495,
  "settlementCurrency": "USD"
}

paymentOverpaid

This webhook is sent when a payment is overpaid.

Attribute	Description
webhookId	This id uniquely identifies an event.
event	Webhook event type.
paymentCode	Unique code to identify the payment.
paidAmount	Amount in fiat currency associated with the payment.
totalPaidAmount	Sum of payments in fiat currency for the invoice.
status	Status of the invoice.
paidDatetime	Time the payment was made.
invoiceCode	Unique code to identify the invoice.
invoiceNumber	Unique number to identify the invoice, relative to your account.
invoicedAmount	Requested amount specified in the invoice for the products or services.
invoiceCurrency	Fiat currency which the invoice is issued and payments are to be made.
settlementNetAmount	Net amount credited to your balance for this payment, after fees, in `settlementCurrency`. `null` when it cannot be determined.
settlementCurrency	Currency `settlementNetAmount` is credited in: your settlement currency for fiat settlement (e.g. `CAD`), or the received cryptocurrency for crypto settlement (e.g. `USDT`). Can differ from `invoiceCurrency`. `null` when it cannot be determined.

Example paymentOverpaid webhook payload:

{
  "webhookId": "be22aaf3-9944-4022-a1e5-2518c33db67b",
  "event": "paymentOverpaid",
  "paymentCode": "pym_lo29sd5wina08tbfikx9xgu8n",
  "paidAmount": 5000,
  "totalPaidAmount": 5000,
  "status": "Overpaid",
  "paidDatetime": "2023-09-15T23:11:03.128Z",
  "invoiceCode": "inv_ozqtnhhavpgcyas32qxnlgkykx",
  "invoiceNumber": "718B4F26-1",
  "invoicedAmount": 3000,
  "invoiceCurrency": "USD",
  "settlementNetAmount": 4950,
  "settlementCurrency": "USD"
}

refundCompleted

This webhook is sent when a refund is completed.

Attribute	Description
webhookId	This id uniquely identifies an event.
event	Webhook event type.
invoiceCode	Unique code to identify the invoice.
invoiceCurrency	Fiat currency which the invoice is issued and payments are to be made.
refundCode	Unique code to identify the refund.
refundAmount	Amount refunded in fiat.
refundDatetime	Time refund was made

Example refundCompleted webhook payload:

{
  "webhookId": "c0597e8d-2df0-40bc-b4d9-31d68c6a55c3",
  "event": "refundCompleted",
  "refundCode": "rfd_qGOvVcvJpy7txM8SAFrdD2e1m8",
  "refundAmount": 12.2,
  "invoiceCode": "inv_c1cpsnsfdjc5mckgw91d1nyt34",
  "invoiceCurrency": "CAD",
  "refundDatetime": "2024-02-09T16:42:25.865Z"
}

cryptoPayoutCreated

This webhook is sent when a crypto payout request is created.

Example cryptoPayoutCreated webhook payload:

Attribute	Description
webhookId	This id uniquely identifies an event.
event	Webhook event type.
cryptoPayoutCode	Unique code to identify the crypto payout.
recipient.firstName	First name of the crypto payout recipient.
recipient.lastName	Last name of the crypto payout recipient.
recipient.address1	Primary address line of the crypto payout recipient.
recipient.address2	Secondary address line of the crypto payout recipient.
recipient.city	City of the crypto payout recipient.
recipient.state	State or province of the crypto payout recipient.
recipient.country	Country of the crypto payout recipient.
recipient.zip	ZIP or postal code of the crypto payout recipient.
sourceAmount	Amount deducted from the source currency.
destinationAmount	Amount the recipient is expected to receive.
network	Blockchain network used for the crypto payout.
walletAddress	Destination wallet address of the recipient.

{
  "webhookId": "457e0528-056a-4ad5-9020-a53dafa0ebd1",
  "event": "cryptoPayoutCreated",
  "cryptoPayoutCode": "cpo_fM9noD1zchG4r7jLI9dWdZH1I6",
  "recipient": {
    "firstName": "Don",
    "lastName": "Bull",
    "address1": "2345, Yonge St",
    "address2": "",
    "city": "Toronto",
    "state": "Ontario",
    "country": "Canada",
    "zip": "M4P 2C8"
  },
  "sourceAmount": 182.66,
  "destinationAmount": 0.0011,
  "network": "Bitcoin",
  "walletAddress": "1BvBMSE3rWetqTFn5Au4m4GFg7xJaNVN2"
}

cryptoPayoutSent

This webhook is sent when a crypto payout has been successfully processed and broadcast to the blockchain network.

Example cryptoPayoutSent webhook payload:

Attribute	Description
webhookId	This id uniquely identifies an event.
event	Webhook event type.
cryptoPayoutCode	Unique code to identify the crypto payout.
recipient.firstName	First name of the crypto payout recipient.
recipient.lastName	Last name of the crypto payout recipient.
recipient.address1	Primary address line of the crypto payout recipient.
recipient.address2	Secondary address line of the crypto payout recipient.
recipient.city	City of the crypto payout recipient.
recipient.state	State or province of the crypto payout recipient.
recipient.country	Country of the crypto payout recipient.
recipient.zip	ZIP or postal code of the crypto payout recipient.
sourceAmount	Amount deducted from the source currency.
destinationAmount	Amount the recipient received.
network	Blockchain network used for the crypto payout.
walletAddress	Destination wallet address of the recipient.
txHash	Blockchain transaction hash.

{
  "webhookId": "457e0528-056a-4ad5-9020-a53dafa0ebd1",
  "event": "cryptoPayoutSent",
  "cryptoPayoutCode": "cpo_fM9noD1zchG4r7jLI9dWdZH1I6",
  "recipient": {
    "firstName": "Don",
    "lastName": "Bull",
    "address1": "2345, Yonge St",
    "address2": "",
    "city": "Toronto",
    "state": "Ontario",
    "country": "Canada",
    "zip": "M4P 2C8"
  },
  "sourceAmount": 182.66,
  "destinationAmount": 0.0011,
  "network": "Ethereum",
  "walletAddress": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
  "txHash": "0x84e4ead4c008feeddd6dcb4998a3b4e09746c43994092cdadfb79e7d990bdfaf"
}

cryptoPayoutError

This webhook is sent when an error occurs during the creation or processing of a crypto payout.

Attribute	Description
webhookId	This id uniquely identifies an event.
event	Webhook event type.
cryptoPayoutCode	Unique code to identify the crypto payout associated with the error.

Example cryptoPayoutError webhook payload:

{
  "webhookId": "457e0528-056a-4ad5-9020-a53dafa0ebd1",
  "event": "cryptoPayoutError",
  "cryptoPayoutCode": "cpo_fM9noD1zchG4r7jLI9dWdZH1I6"
}

cryptoPayoutRevoked

This webhook is sent when a previously created crypto payout request is canceled before it is processed or sent.

Attribute	Description
webhookId	This id uniquely identifies an event.
event	Webhook event type.
cryptoPayoutCode	Unique code to identify the revoked crypto payout.

Example cryptoPayoutRevoked webhook payload:

{
  "webhookId": "457e0528-056a-4ad5-9020-a53dafa0ebd1",
  "event": "cryptoPayoutRevoked",
  "cryptoPayoutCode": "cpo_fM9noD1zchG4r7jLI9dWdZH1I6"
}

Verifying webhook sender

To verify that a webhook is sent by us:

Get a x-eukapay-signature header value and payload as it is without any alteration or converting to json.
Perform calculations on your side to create a digest using your secret key, raw webhook payload in bytes and HMAC SHA-512 Hex algorithm.
Compare x-eukapay-signature header value with calculated digest.

Example of computing digest (JavaScript):

function compareDigest(req): boolean {
  const calculatedDigest = crypto.createHmac('sha512', SECRET_KEY).update(JSON.stringify(req.body)).digest('hex');

  return calculatedDigest === req.headers['x-eukapay-signature'];
}