[tracking202]

Stacked on #276 (ClickBank per-account, branch 1.9.79-clickbank-per-account), which is stacked on #268 (PayKickstart IPN). Review and merge this after #276 (and #268). Until they merge, this diff includes their commits. This PR's own change is 0395bc3, 801e5fc and e6a29f0; e6fb649 merges #276 in. To see it alone: git diff origin/1.9.79-clickbank-per-account...1.9.79-clickbank-rebills-refunds.

Backlog: 851K ("ClickBank rebills are never recorded and refunds never reverse a sale")

What was wrong

cb202.php acted on TEST and SALE only, and answered every other INS notification 200 with nothing done:

• a BILL (a subscription's rebill) recorded no revenue;
• an RFND (refund) or CGBK (chargeback) left the sale counted.

What changed

ClickBankAdapter now reads every transactionType that ClickBank's INS article lists (TYPES). Recording and reversing go through #268's Processor and p202RecordLegacyConversion(), as PayKickstart and JVZoo do.

Type	What ClickBank says it is	What Prosper202 does	Status
SALE	a purchase, or a subscription's first payment	a conversion under its receipt, at totalAccountAmount	200 recorded
BILL	a subscription's rebill	another conversion under its own receipt (ClickBank: the first order's, a dash and four digits, ABCD1234-0001)	200 recorded
RFND	a refund	a reversal of the conversion under its receipt, by what totalAccountAmount says the account lost (sign dropped); none or 0 takes back the whole payment	200 reversed
CGBK	a chargeback	the same	200 reversed
INSF	an eCheck chargeback (the reports' "Bounced": the buyer's bank returned the check)	the same	200 reversed
CANCEL-REBILL	a subscription cancelled (a refunded subscription also sends one)	nothing: no money moves	200 ignored, logged with its account
UNCANCEL-REBILL	a cancellation undone	nothing	200 ignored, logged
SUBSCRIPTION-CHG, ABANDONED_ORDER, CUSTOMER_AUTH_FAILURE, CUSTOMER_EMAIL_UPDATE, CUSTOMER_UPDATE_CC_NOTIFICATION, PURCHASE_DETAILS_EMAIL_RESPONSE	a product change, a cart left, a rebill's card declined, the buyer's details or receipt email	nothing	200 ignored, logged
TEST, TEST_SALE, TEST_BILL, TEST_RFND, CANCEL-TEST-REBILL, UNCANCEL-TEST-REBILL	tests	the key is marked Verified; nothing is recorded	200 test
any other	not in the article	nothing	400, naming it

Reversals (#268's rules, with one change for ClickBank in e6a29f0):

• A payment is reversed once. Only ClickBank's retry of the same notification (the same order, attemptCount aside) is 200 duplicate. Any other reversal of a payment that already has one is a 409 naming the reversal on file and how much is still credited, whatever amount it states. That includes a second partial refund of the same amount and a chargeback of a refunded payment.
  • Until e6a29f0 the Processor compared the amount only, so a second 10.00 refund after a 10.00 refund was answered 200 duplicate ("is already reversed; nothing was changed"). ClickBank never retries a 200, so the refund was lost without trace (CLAUDE.md subid missing in pixel url #4, [Fix] Return 404 status #15). Found by a self-review after the adversarial review marked this PR BLOCKING.
  • PayKickstart keys refunds by its form fields and keeps the amount-only rule.
  • A second partial refund is now refused loudly rather than recorded. Recording several partial reversals of one payment is a change to the shared Processor, filed separately.
• A SALE sent again while its refund stands is a 409 that names the reversal to delete.
• A refund with no id of its own is keyed by its body, so after a reversal is deleted the same notification still changes nothing, while another one reverses the sale again.
• A refund is dated by its own transactionTime, held at its sale when it is earlier.

A shared fix this needed. The Processor keys that body by hashing $request->fields. ClickBank's notification is a JSON body with no form fields, so every ClickBank refund had the same key. Driven before the fix: a sale was refunded, an operator deleted the reversal, then a chargeback arrived. It was answered 200 "this CGBK is that refund sent again" and the sale stayed counted.

• Fix: a new optional interface, FingerprintsNotifications. The Processor asks it when the adapter implements it. This is one instanceof in Processor::reversal(); PayKickstart and JVZoo are untouched.
• ClickBank's answer is the decrypted order, with its keys in order and without attemptCount. ClickBank raises attemptCount on each retry of the same notification, and a retry's ciphertext and IV need not repeat.

Docs and changelogs. The ClickBank outcome table in documentation/tutorials-and-guides/09-3rd-party-integrations.md now covers every type. The setup steps say to set a subscription campaign's When a click converts more than once to Add them up. There are entries in changelogs.txt and changelogs.json, after 1.9.79's own.

Checked against ClickBank's spec

The type names and meanings were re-read from support.clickbank.com "Instant Notification Service (INS)" (article 10535147), not from memory. The receipts came from the transaction-reporting articles.

• Verified:
  • the 17 types and their descriptions in the table above;
  • "Refunded recurring products also generate a CANCEL-REBILL";
  • rebill receipts are "the same receipt number as the initial order, followed by a dash and four-digit number";
  • partial refunds exist: the Orders API's product change refunds "a portion of the old product's last recurring payment".
• Not verified:
  • The refund's receipt. No article says whether an RFND, CGBK or INSF carries the receipt of the payment it takes back. This PR reverses the conversion under the notification's own receipt.
  • The amount's sign. No article says whether totalAccountAmount is negative on a refund; both signs are read. A third-party affiliate guide (affiliatedegen.com) records refunds as negative amounts against the same tracking value, which also suggests that refunds carry the order's tracking codes.
  • No real ClickBank notification was available.

The ledger rules (CLAUDE.md #13, #15, #34, #36)

• [Fix] Return 404 status #15. A retry under a receipt on file is compared with the record, never answered as the first. A sale stating another amount is a 409. A reversal is compared by its fingerprint, the decrypted order without attemptCount, rather than by amount, so only a retry of the same notification is a duplicate.
• [Core] Update PHP version check for PHP 8 #13. A failure answers 500 and ClickBank retries in 4 hours. The writer keys the row by the receipt (and the reversal by sale and body), so a retry cannot double it.
• Fix undefined mysql array keys #34 and Fix undefined array key warnings and TypeError in aff_campaigns.php #36. Recording goes only through p202RecordLegacyConversion(), whose writer locks the click before its first plain read and owns its transaction. The Processor catches nothing inside a transaction.

Decisions a reviewer should check

1. A type the article does not list is a 400, not 200 ignored. The brief said "other types are acknowledged and logged". Every type the article lists is acknowledged and logged. An unlisted one is refused by name, as JVZoo (1.9.79: JVZoo's JVZIPN at jvzoo.php, for affiliates and vendors (stacked on #268) #272) refuses: acknowledging it would lose a type that moves money (the older API's SALE-RB/RFND-RB, say) with no trace in ClickBank's log. ClickBank retries a 400 five times over 20 hours.
2. Differences from JVZoo:
   • Partial reversals. JVZoo reverses in full because JVZoo refunds whole; ClickBank refunds part of a payment too.
   • Unknown fields are not refused, as 1.9.79: ClickBank's INS works for every account, decrypted with each account's own key #276 explains: the order is encrypted whole, and its fields grow by version.
   • Same as JVZoo: INSF reverses; CANCEL-REBILL and UNCANCEL-REBILL are acknowledged with nothing recorded; the account is the one whose key verifies.
3. TEST_SALE and the other test types mark the key Verified, as TEST does, because each one decrypted with that account's key.
4. SUBSCRIPTION-CHG records nothing. The article describes it by its old and new products, not by a payment.
5. A chargeback of a refunded payment for the same amount is a 409 (since e6a29f0), where it was 200 duplicate. Two notifications that each say the account lost the money then both show in ClickBank's log, and neither is dropped unseen.

Verification

Scope report of .claude/skills/p202-verify/scripts/verify.sh --since origin/1.9.79 --changed on 801e5fc (PHP 8.3.6, MariaDB 10.11, full vendor/). The schema tier had a scratch database, and 202-config.php was moved aside. Unit tier: 6170 tests, 4 skipped (the documented User DB-singleton skips). Verbatim:

Scope report
------------
  go         PASS  ran under CI's go1.25.14 via GOTOOLCHAIN (local go is 1.24)
  golangci   PASS  ran under CI's go1.25.14 via GOTOOLCHAIN (local go is 1.24)
  openapi    PASS
  patterns   PASS
  phpcs      PASS
  phpstan    PASS
  schema     PASS
  syntax     PASS
  unit       PASS

Not covered by this script:
  live      stand up an instance, drive the path a user would take
  agent     add and run a case under tests/fixtures/agent-eval/cases/
  ci        a workflow still in_progress has not passed; read the run

For e6a29f0, verify.sh --changed on the working tree before the commit gave patterns, phpcs, phpstan, syntax and unit PASS.

Integration suites, each alone on a database created for it:

Suite	Tests
ClickBankInsIntegrationTest	24 OK (after e6a29f0)
PayKickstartIpnIntegrationTest	20 OK
LegacyPostbackCampaignIntegrationTest	5 OK
ConversionBridgeIntegrationTest	5 OK
ConversionLedgerIntegrationTest	26 OK

The integration tests cover:

• a rebill beside its sale;
• a refund and ClickBank's retries of it;
• a second refund of the same amount, refused;
• a partial refund, and the full one refused after it;
• a chargeback and a returned eCheck in full;
• a refund of a rebill alone;
• a sale sent again after its refund;
• a reversal deleted and then a chargeback;
• refund dating;
• another account's click;
• cancellations and an unlisted type.

testAnotherRefundOfTheSameAmountIsRefusedNotAnsweredAsTheFirst fails without e6a29f0's Processor change.

Planted defects, 19 of 19 caught, each by a named test:

• BILL, RFND, CGBK or INSF dropped;
• CANCEL-REBILL reversing;
• TEST_SALE recorded;
• an unlisted type acknowledged;
• every reversal in full;
• a stated 0 reversing nothing;
• a reversal naming no receipt;
• a negative rebill accepted;
• a retry's attemptCount kept in the fingerprint;
• the Processor fingerprinting the form fields;
• the fingerprint not in key order;
• a time read without its offset;
• a 13th month read as January;
• a reversal not dated, a sale not dated;
• an unreadable time read as none.

Live pass, tests/live/clickbank-ins.sh: 85 passed, 0 failed on 801e5fc. After e6a29f0: 87 passed, 0 failed. The two new steps are a retry sent as the identical order and a second refund of the same amount, now a 409. With the Processor change taken out, those two fail.

Two accounts, notifications encrypted by the openssl command line, posted with curl, rows read back from 202_conversion_logs and GET /conversions. Beyond #276's checks:

• a BILL under RB…-0001 recorded and replayed as a duplicate;
• account 2's RFND reverses its sale by 12.50 (reverses_conv_id set), and its replay is a duplicate;
• a CGBK of the refunded sale for another amount is a 409;
• account 1's key cannot refund account 2's rebill (404);
• a CGBK stating 0 takes the whole rebill back, and account 2's click nets 0;
• an INSF takes back account 1's sale;
• a refund of a receipt not on file is a 404;
• CANCEL-REBILL, UNCANCEL-REBILL and SUBSCRIPTION-CHG are 200 ignored, and TEST_SALE is 200 test;
• RFND-RB is a 400 naming it;
• GET /conversions?source=clickbank lists the four rows to account 2 and none to account 1;
• a reversal deleted through DELETE /conversions/{id}: ClickBank's retry of the same refund is 200 "that refund sent again", a chargeback then reverses the sale again, and the SALE sent again is a 409;
• the server log has one line per notification, naming its account, with no key and no buyer detail.

Before and after. The same pass against #276's adapter: 61 passed, 24 failed, with every BILL, RFND, CGBK, INSF, TEST_SALE and unlisted type answered 200 ignored.

Could not run

• The installer's licence step. The licence stub at my.tracking202.com is down. The instance was installed by running what 202-config/install.php does once its licence check passes: INSTALL::install_databases(), InstallAccount::create(), a REST API key in 202_api_keys, and the partitions. Then php -S was started with the CI router, as install-instance.sh does. Skipped: the licence check itself, and the AutoCron and daily-email registrations. Everything else (the API, dl.php, cb202.php, DELETE /conversions/{id}) was driven directly.
• CI has not been observed on e6a29f0 yet.
• A real ClickBank notification was not available.
• The full integration-suite set was not run. The run was on MariaDB 10.11; CI runs MySQL 8.0.

Found outside this item

• A reversal larger than its sale is recorded as stated. A refund of a 20.00 sale stating 37.62 leaves the click at −17.62. This is the shared Processor's behaviour (PayKickstart too). For a ClickBank vendor it may even be right, if ClickBank's refund costs more than the sale's net. It needs a decision (backlog 3E5N).
• The shared Processor's no_click and unknown_click messages are worded for PayKickstart ("the checkout link carried no subid", "signed"). ClickBank and JVZoo answer no_click from their adapters to avoid this. 1.9.79: payment notifications answer no_click and unknown_click in each provider's own field names #319 fixes the rest.

---

Generated by Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	⚠️ Failed 2026-10-28T05:56:03.890812Z We couldn’t complete this review. Comment @codex review to try again.	801e5fc	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

[github-actions]

Code review: CLEAN

For 801e5fc: 0 issue(s). The review is encrypted for the maintainers in the review-findings artifact of this run.

[github-actions]

Adversarial review: NON-BLOCKING

For 5e7e990: 6 finding(s). The report is encrypted for the maintainers in the review-findings artifact of this run.

Rewritten on every push; the check fails on BLOCKING.

[tracking202]

adversarial-review failed on f750f9d, the merge of 1.9.79 into this branch: verdict BLOCKING, 6 findings. The findings are encrypted for maintainers, so I can't read which ones block.

I've started an independent adversarial review of the same diff: this branch's commits, #276's and #268's beneath it, and the merge resolutions. Every defect it can show with a failing test gets fixed on the lowest branch that owns the code, then merged up. If a maintainer can share which findings were blocking, that would point the fixes directly.

---

Generated by Claude Code

[tracking202]

This follows up the BLOCKING adversarial review on f750f9d. Its report is encrypted, so we can't confirm that this is the same finding, but a self-review of this PR's own delta found one defect and e6a29f0 fixes it.

• Defect: a second ClickBank refund of a payment for the same amount was answered 200 duplicate and dropped, and ClickBank never retries a 200. The Processor compared amounts even when the adapter's fingerprint had already shown it was a different notification.
• Fix: only ClickBank's retry of the same order is a duplicate. Any other reversal of a payment that already has one is a 409 naming what is still credited.
• Behaviour change: a chargeback of a refunded payment for the same amount is now a 409 too, where it was 200 duplicate.
• Test: testAnotherRefundOfTheSameAmountIsRefusedNotAnsweredAsTheFirst fails without the change.
• Live pass: 87 passed, 0 failed with the change. With the Processor change taken out, the two new steps fail.

The description above is updated to match. The review re-runs on this push.

---

Generated by Claude Code