Webhooks not implemented: processNotification is a stub, async scheme events are never recorded
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 30/100
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:
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:
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
- Implement
processNotificationto parse the GoCardless webhook envelope and return aGatewayNotification. - Verify the
Webhook-SignatureHMAC-SHA256 header against a per-tenant webhook secret; add the secret toGoCardlessConfigProperties. - Handle the event batch (GoCardless posts arrays of events) idempotently, keyed on event id.
- Map events onto the corresponding Kill Bill payment transaction and notify via
PaymentApi#notifyPendingTransactionOfStateChanged(or equivalent). - Fix
purchasePaymentto returnPENDINGfor 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
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from killbill/killbill-gocardless-plugin
-
Migrate from deprecated Redirect Flows to Billing Requests (blocked on gocardless-pro SDK upgrade)Open
Difficulty 4/5 3-5 days Newbie friendliness 18/100
-
Difficulty 5/5 Over a week Newbie friendliness 18/100
-
Difficulty 4/5 3-5 days Newbie friendliness 33/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 35/100
All issues in killbill/killbill-gocardless-plugin
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
-
RegistryExceptionHandler uses self-referencing basePackageClasses instead of a controller classOpenbug finsim-registry good-first-issue
Difficulty 1/5 Under an hour Newbie friendliness 88/100
Maintainers usually reply within 1 day
-
status:pending type:bug
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
bug level:trivial
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
exoego/keycloak-fuhito#666 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 79/100
hammy275/immersive-mc#669 ·