Payment Bearer Expiring

This webhook notifies you about a payment bearer that is due to expire soon (typically a credit card). You probably want to inform your customer and ask them to provide new payment information. This hook will be triggered even for contracts that have ended, but you can filter such contracts in your webhook handler.

Typical Scenario

The credit card expires in one month and you want to show the customer a notification, that the current payment method will be invalid shortly.

{
    "Event" : "PaymentBearerExpiring",
    "ContractId" : "51d970c8eb596a1168df119a",
    "ExpiryDate" : "2013-12-22T11:11:11Z"
}

Debit Auth Cancelled

This webhook is triggered when the authorization to debit money has been revoked either by the customer or PSP. The next payment will fail and you probably want to take appropriate action.

Typical Scenario

A customer cancelled the payment authorization in PayPal, the webhook is triggered and you can show a notification to the customer, that there's no valid payment method stored.

{
    "Event" : "DebitAuthCancelled",
    "ContractId" : "51d970c8eb596a1168df119a",
    "CustomerId" : "51d140d8fc787ac88a4afc4a",
    "YourCustomerId" : "23213",
    "PaymentProvider" : "PayPal",
}

Payment Data Changed

This webhook is triggered when a new payment bearer is assigned to a contract (e.g. customer has entered new credit card data after the old card expired).

Typical Scenario

The payment data was changed and you want to notify the customer, that the change was successful.

{
    "ContractId":"6298a006e636b694d807080f",
    "CustomerId":"6298a006e636b694d8070809",
    "Event":"PaymentDataChanged",
    "EntityId":"62148e3c0c14e1609e9ca5c1"
}

Payment Escalated

This webhook is triggered based on your payment escalation settings.

📘

Note

The Payment Escalated webhook contains no dunning document information. If you would like to receive information for dunning creation, you have to subscribe to the DunningCreated webhook.

Typical Scenario

You can use this hook to react to your customers non-payment, for example by sending a notification email or by suspending the account.

The value of TriggerDays is the number of days since the payments due date. This is based on the oldest unpaid receivable, so it's possible that you receive a five-day-hook, then a ten-day-hook and a five-day-hook again.

📘

Note

Chargebacks have an impact on the difference between the planned TriggerDays and reality. If you receive the chargeback 10 days after the DueDate, the escalation starts 10 days later than expected.

PaymentEscalationProcessId: Id of the database object holding the escalation settings of the legal entity.

{
    "ContractId": "6298a006e636b694d807080f",
    "CustomerId": "6298a006e636b694d8070809",
    "TriggerDays": 5,
    "DueDate": "2022-06-09T00:00:00.0000000Z",
    "PaymentEscalationProcessId": "623812c0426dc88abe51b23a",
    "Event": "PaymentEscalated",
    "EntityId": "62148e3c0c14e1609e9ca5c1"
}

Payment Escalation Reset

This webhook is triggered when an escalation process was reset automatically or manually. An automatic reset happens when the customer paid the vacant positions. The process can also be reset manually by you.

Typical Scenario

A customer paid the open receivables and now you want to unlock the service for him.

{
    "ContractId":"6298a006d2044479fc05e9e4",
    "CustomerId":"6298a006e636b694d8070809",
    "Event":"PaymentEscalationReset",
    "EntityId":"62148e3c0c14e1609e9ca5c1"
}

Payment Succeeded

This webhook is sent when a payment was successfully completed. Usually, it's not required that you worry about this in your application.

Typical Scenario

Remark: Use Order Succeeded instead and Payment Succeeded for further controlling, if there are outstanding receivables

{
    "Event" : "PaymentSucceeded",
    "PaymentTransactionId" : "51d970c8eb596a1168df119a"
}

Payment Failed

This webhook is triggered when a payment transaction failed.

Typical Scenario

Remark: In most cases, it's not required nor suggested to handle this webhook yourself. Use Payment Escalated instead.

{
    "Event" : "PaymentSucceeded",
    "PaymentTransactionId" : "51d970c8eb596a1168df119a"
}

Payment Process Status Changed

There are different reasons why a payment process for a contract is paused, e.g several payment retries failed. In such cases billwerk stops any further payment processes. You might want to get informed about these events to take appropriate action. This webhook will be triggered if the process is stopped or started.

Typical Scenario

Due to a direct debit chargeback, the recurring payments are switched off for this contract and the webhook ist triggered. After checking the status of RecurringPaymentsPaused inside the contract you want to inform the customer about a heavy payment problem.

{
    "ContractId":"629479fd471b3f8ab4ad08e0",
    "CustomerId":"6242991221642365b05d86a9",
    "Event":"PaymentProcessStatusChanged",
    "EntityId":"62148e3c0c14e1609e9ca5c1"
}

Payment Registered

Sometimes you might have external payments/refunds outside of billwerk (e.g. bank transfer by your customer). These payments are either registered manually or via account reconciliation. This webhook will be triggered when a new external payment/refund is registered in billwerk.

Typical Scenario

After registering an external payment for a contract, you want to get the current balance of the contract.

{
    "ContractId":"6298a006e636b694d807080f",
    "CustomerId":"6298a006e636b694d8070809",
    "Event":"PaymentRegistered",
    "EntityId":"62148e3c0c14e1609e9ca5c1"
}

Payment Status Changed

You can use it to receive information about any changes in Payment Transaction Status

{
  "ContractId":"66eaee31c103a175cb9c512e",
  "CustomerId":"66eaee30c103a175cb9c50e9",
  "PaymentTransactionId":"673b4f3f644df9de2a0789f8",
  "Status":
    {
      "Status":"InProgress",
      "Timestamp":"2024-11-18T14:29:19.0640000Z",
      "Amount":0,
      "HttpCode":0,
      "Preauth":true
    },
  "Event":"PaymentStatusChanged",
  "EntityId":"66d84149440b33083da0a388"
}

{
  "ContractId":"673b55473f54df4e076baaed",
  "CustomerId":"673b55473f54df4e076baaec",
  "PaymentTransactionId":"673b554888609962ada515e5",
  "Status":
    {
      "Status":"Failed",
      "Timestamp":"2024-11-18T14:55:22.3150000Z",
      "ErrorCode":"InsufficientBalance",
      "ProviderMessage":"Your card has insufficient funds.",
      "HttpCode":402,
      "Preauth":true
    },
  "Event":"PaymentStatusChanged",
  "EntityId":"66d84149440b33083da0a388"
}