Webhooks not implemented: processNotification is a stub, async scheme events are never recorded

Open
#43 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
30/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Quiet
Tech stack
java
Domain
payments

Research direction

Start in GoCardlessPaymentPluginApi.java at the processNotification stub (lines 429-432) and the purchasePayment status mapping (line 113). Read the existing convertGoCardlessToKillBillStatus helper and GoCardlessConfigProperties to see how statuses and tenant config are handled. Done means processNotification parses the GoCardless webhook envelope, verifies the Webhook-Signature HMAC-SHA256 header, handles event batches idempotently by event id, maps events onto Kill Bill transactions and notifies via PaymentApi, and purchasePayment returns PENDING for non-terminal states so the Janitor can re-poll.

Written by the indexing model from the issue text.

Description

Problem

processNotification is a stub that always throws:

https://github.com/killbill/killbill-gocardless-plugin/blob/main/src/main/java/org/killbill/billing/plugin/gocardless/GoCardlessPaymentPluginApi.java#L429-L432

throw new PaymentPluginApiException("INTERNAL", "#processNotification not yet implemented, please contact [email protected]");

This means the plugin has no way to learn about anything GoCardless reports asynchronously.

Why this matters

Bank debit schemes are inherently asynchronous. A BACS collection takes roughly 3 working days to clear; SEPA Core and ACH have comparable delays. Practically everything interesting happens after the API call that created the payment returns:

GoCardless event Consequence for Kill Bill today
payments.confirmed / payments.paid_out never recorded
payments.failed (insufficient funds, account closed) invoice stays marked paid
payments.charged_back / chargeback_settled never recorded
mandates.cancelled / mandates.failed / mandates.expired payment method stays active, subsequent collections fail
refunds.* never recorded
payouts.paid no settlement/reconciliation signal

Aggravating factor

purchasePayment reports success synchronously, before the bank has done anything:

https://github.com/killbill/killbill-gocardless-plugin/blob/main/src/main/java/org/killbill/billing/plugin/gocardless/GoCardlessPaymentPluginApi.java#L113

TransactionType.PURCHASE, amount, currency, PaymentPluginStatus.PROCESSED, null, null,

At that moment the GoCardless payment is pending_submission, not collected. Because the transaction is recorded as PROCESSED rather than PENDING, the Kill Bill Janitor will not re-poll the plugin, so even the polling fallback via getPaymentInfo never kicks in. A collection that fails three days later is invisible to Kill Bill forever.

Note that the correct mapping already exists and is unused on this path — convertGoCardlessToKillBillStatus maps PENDING_SUBMISSION / SUBMITTED to PaymentPluginStatus.PENDING.

Proposed work

  1. Implement processNotification to parse the GoCardless webhook envelope and return a GatewayNotification.
  2. Verify the Webhook-Signature HMAC-SHA256 header against a per-tenant webhook secret; add the secret to GoCardlessConfigProperties.
  3. Handle the event batch (GoCardless posts arrays of events) idempotently, keyed on event id.
  4. Map events onto the corresponding Kill Bill payment transaction and notify via PaymentApi#notifyPendingTransactionOfStateChanged (or equivalent).
  5. Fix purchasePayment to return PENDING for non-terminal GoCardless states, so the Janitor polling path works as a safety net even if a webhook is missed.

Items 1–4 and item 5 are separable; item 5 alone materially reduces the blast radius and could land first.

Dominant language
Java
Stars
4
Forks
7
PR merge metrics
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from killbill/killbill-gocardless-plugin

All issues in killbill/killbill-gocardless-plugin

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.