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

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

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

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.
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.

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"
}

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.

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"
}

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.

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"
}

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.
refundedDatetime	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",
  "cryptoPayout": "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",
  "cryptoPayout": "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": "0x30f283LAa894mdi942b8D5638560933973F081e4",
  "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",
  "cryptoPayout": "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",
  "cryptoPayout": "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'];
}