How does Kill Bill reconcile an unresolved gateway outcome?

[Daniel Lindberg]

Hi Kill Bill community,

I’m trying to understand one narrow recovery path in Kill Bill’s payment flow.

Suppose a transaction remains UNKNOWN, or remains PENDING beyond the expected asynchronous window, while the payment gateway already has a determinate outcome.

In practice, what normally closes that gap first: a plugin notification, polling or reconciliation, a repair operation, manual intervention, or something else?

From reading the payment-state documentation and plugin interface, my current guess is that plugin notifications normally close the gap first, while polling or repair handles missed or ambiguous outcomes—but I suspect the real ordering is gateway-specific.

If this is primarily plugin-specific, a pointer to the relevant plugin maintainer or documentation would also be very helpful.

Best,
Daniel Lindberg

[stephane brossier]

Hi Daniel,

From our payment documentation: PENDING and UNKNOWN transaction states should be temporary; the payment plugin needs to eventually tell Kill Bill what the final state of these transactions should be. This can be done explicitly by the plugin by calling the PaymentApi.notifyPendingTransactionOfStateChanged (for instance, when receiving a webhook event from the gateway) or implicitly by the Janitor.

Does it helpn with your question or if not could you clarify exactlky what is missing?

Stéphane

--
You received this message because you are subscribed to the Google Groups "Kill Bill users mailing-list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to killbilling-us...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/killbilling-users/fce87fe6-9957-41aa-b479-2be458029530n%40googlegroups.com.

[Daniel Lindberg]

Thanks, Stéphane — that clarified the designed recovery paths: the plugin closes the gap explicitly via PaymentApi.notifyPendingTransactionOfStateChanged, with the Janitor providing the implicit recovery path.

I’m also curious whether anyone on the list has seen either path not close cleanly in practice: for example, a transaction remaining PENDING or UNKNOWN after the gateway already had a final outcome, while a later payment action or state transition was evaluated before the local state was updated.

Even a rough, sanitized recollection would be useful. And if this simply has not been observed in practice, that is equally useful to know.

Best,
Daniel

[stephane brossier]

Hi Daniel,

The mechanism I described is typically enough to cover those cases, but we also provide administrative APIs that could you use in the unlikely scenario where reconcilation needs to be overiden 'by hand' - See https://apidocs.killbill.io/admin#update-the-state-of-a-paymenttransaction-and-associated-payment

Best,

Stéphane

To view this discussion visit https://groups.google.com/d/msgid/killbilling-users/aa5774bb-b967-4541-9705-29e49a77116an%40googlegroups.com.

[Daniel Lindberg]

Hi Stéphane,

Thank you — that clarifies the manual recovery path beyond the plugin notification and Janitor mechanisms.

Have you seen the administrative API used in practice because Kill Bill’s local payment-transaction state and the gateway’s final outcome could not be reconciled automatically? If so, what evidence did the operator rely on to determine the final state before overriding it?

Even a brief sanitized example would teach me a lot.

Best,
Daniel

[stephane brossier]

I do not have direct visibility into customer deployments, but there are several scenarios where automatic reconciliation can fail. For instance, notifications could be dropped, a payment plugin might be incorrectly implemented (e.g., missing reverse chargeback logic), or a payment gateway might have limited APIs that prevent state reconciliation entirely.

In all of these scenarios, having a manual mechanism to fix the state is very useful.

To view this discussion visit https://groups.google.com/d/msgid/killbilling-users/93fec09f-8213-437a-81b9-19858c66c00bn%40googlegroups.com.

[Daniel Lindberg]

Hi Stéphane,

Yes, that answers the question clearly. The distinction between dropped notifications, incomplete plugin behavior, and gateways whose APIs cannot support full reconciliation is especially helpful.

I understand that you do not have direct visibility into customer deployments, so I won’t press for one. Thank you for taking the time to explain the recovery paths and the role of the administrative override.

Best,
Daniel