From 70e914eca5a2a558af2a0d9dcc99df49a494d764 Mon Sep 17 00:00:00 2001 From: Jaafar Date: Wed, 18 Nov 2026 11:47:23 +0200 Subject: [PATCH] fix: verify the card-token webhooks, and surface the card they carry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `card_token.created` and `card_token.failed` were unverifiable. The server signs by opt-out — PaymentIntegrationWebhookJob copies the payload and unsets a fixed exclusion list before hashing — so the tokenisation block it writes for these two events is signed in full: `tokenization_id`, `external_reference`, and, once the card is vaulted, `card_token`, `card_brand`, `card_last4`, `card_exp_month` and `card_exp_year`. This SDK signed none of them, so every card-token webhook failed verification. Both events are on by default for every integration, because a hosted tokenisation has no other way to deliver its token, so this reached anyone saving cards. The signed values are now rebuilt the way the server assembles them, a block at a time: a block is gated on its own leading field, and a key keeps the position it was first written at. That ordering is the whole of it — the signature is a separator-less concatenation, and on an event with no mandate `external_reference` is signed after `tokenization_id`, not at the slot it holds on a subscription event. The card is also readable off WebhookEvent now. The record keeps a constructor with its previous shape so positional construction still compiles. Two golden vectors cover the vaulted card and a failed tokenisation that carries no card at all; they are the same vectors the other SDKs verify against. --- CHANGELOG.md | 16 ++++ paylink-core/pom.xml | 2 +- .../paylink/webhook/DefaultWebhooks.java | 61 +++++++++--- .../paylink/webhook/WebhookEvent.java | 37 +++++++- .../paylink/webhook/WebhookEventType.java | 2 + .../com/getpayin/paylink/WebhookTest.java | 94 +++++++++++++++++-- .../src/test/resources/golden-signatures.json | 60 ++++++++++++ paylink-spring-boot-starter/pom.xml | 4 +- pom.xml | 2 +- 9 files changed, 253 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 301ed5d..6358e8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,22 @@ All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.3.0] - 2026-11-18 + +### Fixed + +- `webhooks().verify()` now accepts `card_token.created` and `card_token.failed`. Both carry the + tokenisation and the card it produced, and the server signs all of those fields; this SDK signed + none of them, so every card-token webhook failed verification. Both events are on by default for + every integration, so any integrator saving cards was receiving webhooks it could not verify. + +### Added + +- `CARD_TOKEN_CREATED` and `CARD_TOKEN_FAILED` on `WebhookEventType`. +- The saved card on `WebhookEvent`: `tokenizationId()`, `cardToken()`, `cardBrand()`, `cardLast4()`, + `cardExpMonth()` and `cardExpYear()`. The record keeps a constructor with its previous shape, so + code that builds an event positionally still compiles. + ## [0.2.0] ### Added diff --git a/paylink-core/pom.xml b/paylink-core/pom.xml index c1f5b0a..08fd35f 100644 --- a/paylink-core/pom.xml +++ b/paylink-core/pom.xml @@ -7,7 +7,7 @@ com.getpayin.paylink paylink-parent - 0.2.0 + 0.3.0 paylink-core diff --git a/paylink-core/src/main/java/com/getpayin/paylink/webhook/DefaultWebhooks.java b/paylink-core/src/main/java/com/getpayin/paylink/webhook/DefaultWebhooks.java index 6b30d42..c158880 100644 --- a/paylink-core/src/main/java/com/getpayin/paylink/webhook/DefaultWebhooks.java +++ b/paylink-core/src/main/java/com/getpayin/paylink/webhook/DefaultWebhooks.java @@ -16,15 +16,32 @@ /** * Default webhook verifier. Recomputes the signature over the concatenated values of an * ordered subset of the payload, exactly as the server signs it: {@code success}, - * {@code invoice_id}, {@code invoice_status}, {@code message}, plus (for subscription - * events only, detected by presence) {@code mandate_id}, {@code external_reference}, - * {@code subscription_status}. The signature travels in the payload body. + * {@code invoice_id}, {@code invoice_status}, {@code message}, then whichever of the two + * optional blocks the payload carries — a recurring mandate's fields, or a card-token + * event's tokenisation and card. The signature travels in the payload body. */ public final class DefaultWebhooks implements Webhooks { private static final List ALWAYS_SIGNED = List.of("success", "invoice_id", "invoice_status", "message"); - private static final List OPTIONAL_SIGNED = List.of("mandate_id", "external_reference", "subscription_status"); + /** The fields a recurring mandate adds, in the order the server adds them. */ + private static final List MANDATE_SIGNED = List.of("mandate_id", "external_reference", "subscription_status"); + + /** + * The fields a card-token event adds, in the order the server adds them. + * + *

{@code card_token.created} and {@code card_token.failed} are the only events that carry a + * tokenisation, and both are on by default for every integration. The server writes + * {@code tokenization_id} and {@code external_reference} first, then the card's details — and + * only when the card was actually vaulted, so a failed tokenisation signs the first two alone. + * + *

Order matters because the signature is a separator-less concatenation: on an event with no + * mandate, {@code external_reference} is signed AFTER {@code tokenization_id}, not at the + * position it holds on a subscription event. + */ + private static final List TOKENIZATION_SIGNED = List.of( + "tokenization_id", "external_reference", "card_token", "card_brand", "card_last4", + "card_exp_month", "card_exp_year"); private final PaylinkConfig config; @@ -69,16 +86,32 @@ public boolean isValid(String payload, String hashToken) { } } + /** + * Rebuilds the expected signature the way the server assembles it. + * + *

{@code PaymentIntegrationWebhookJob} appends a whole block at a time — the mandate fields + * when the invoice belongs to one, the tokenisation fields when the event is about a card — and + * PHP keeps a key at the position it was first written. A block is therefore gated on its own + * leading field rather than on the individual fields inside it: {@code external_reference} + * belongs to whichever block introduced it, and is never signed twice. + */ private String computeSignature(JsonObject object, String hashToken) { + List keys = new ArrayList<>(ALWAYS_SIGNED); + for (List block : List.of(MANDATE_SIGNED, TOKENIZATION_SIGNED)) { + if (!object.has(block.get(0))) { + continue; + } + for (String key : block) { + if (object.has(key) && !keys.contains(key)) { + keys.add(key); + } + } + } + List values = new ArrayList<>(); - for (String key : ALWAYS_SIGNED) { + for (String key : keys) { values.add(fieldToWire(object, key)); } - for (String key : OPTIONAL_SIGNED) { - if (object.has(key)) { - values.add(fieldToWire(object, key)); - } - } return Signature.build(values, hashToken); } @@ -111,7 +144,13 @@ private WebhookEvent toEvent(JsonObject object) { Json.strOrNull(object, "external_reference"), Json.strOrNull(object, "subscription_status"), Json.strOrNull(object, "event_triggered_at"), - Json.strOrNull(object, "timezone")); + Json.strOrNull(object, "timezone"), + Json.strOrNull(object, "tokenization_id"), + Json.strOrNull(object, "card_token"), + Json.strOrNull(object, "card_brand"), + Json.strOrNull(object, "card_last4"), + Json.strOrNull(object, "card_exp_month"), + Json.strOrNull(object, "card_exp_year")); } private JsonObject parse(String payload) { diff --git a/paylink-core/src/main/java/com/getpayin/paylink/webhook/WebhookEvent.java b/paylink-core/src/main/java/com/getpayin/paylink/webhook/WebhookEvent.java index 3a425b1..821c503 100644 --- a/paylink-core/src/main/java/com/getpayin/paylink/webhook/WebhookEvent.java +++ b/paylink-core/src/main/java/com/getpayin/paylink/webhook/WebhookEvent.java @@ -2,7 +2,12 @@ import java.util.Map; -/** A verified webhook event; {@code raw} holds the full decoded body. */ +/** + * A verified webhook event; {@code raw} holds the full decoded body. + * + *

The card components are filled only on {@code card_token.created}, and only once the card was + * actually vaulted: a {@code card_token.failed} event carries the tokenisation and nothing else. + */ public record WebhookEvent( String event, boolean success, @@ -15,5 +20,33 @@ public record WebhookEvent( String externalReference, String subscriptionStatus, String eventTriggeredAt, - String timezone) { + String timezone, + String tokenizationId, + String cardToken, + String cardBrand, + String cardLast4, + String cardExpMonth, + String cardExpYear) { + + /** + * The shape this record had before it carried a card, so code that constructs an event + * positionally still compiles. + */ + public WebhookEvent( + String event, + boolean success, + Map raw, + Long invoiceId, + String invoiceStatus, + String message, + String authCode, + String mandateId, + String externalReference, + String subscriptionStatus, + String eventTriggeredAt, + String timezone) { + this(event, success, raw, invoiceId, invoiceStatus, message, authCode, mandateId, + externalReference, subscriptionStatus, eventTriggeredAt, timezone, + null, null, null, null, null, null); + } } diff --git a/paylink-core/src/main/java/com/getpayin/paylink/webhook/WebhookEventType.java b/paylink-core/src/main/java/com/getpayin/paylink/webhook/WebhookEventType.java index 3aa8dce..20dfc32 100644 --- a/paylink-core/src/main/java/com/getpayin/paylink/webhook/WebhookEventType.java +++ b/paylink-core/src/main/java/com/getpayin/paylink/webhook/WebhookEventType.java @@ -24,6 +24,8 @@ public final class WebhookEventType { public static final String VCC_PAYMENT_FAILED = "vcc.payment_failed"; public static final String CARD_TOKEN_CHARGE_SUCCEEDED = "card_token.charge_succeeded"; public static final String CARD_TOKEN_CHARGE_FAILED = "card_token.charge_failed"; + public static final String CARD_TOKEN_CREATED = "card_token.created"; + public static final String CARD_TOKEN_FAILED = "card_token.failed"; private WebhookEventType() { } diff --git a/paylink-core/src/test/java/com/getpayin/paylink/WebhookTest.java b/paylink-core/src/test/java/com/getpayin/paylink/WebhookTest.java index 1019687..ea727f8 100644 --- a/paylink-core/src/test/java/com/getpayin/paylink/WebhookTest.java +++ b/paylink-core/src/test/java/com/getpayin/paylink/WebhookTest.java @@ -10,6 +10,7 @@ import com.getpayin.paylink.exception.PaylinkSignatureException; import com.getpayin.paylink.internal.Signature; import com.getpayin.paylink.webhook.WebhookEvent; +import com.getpayin.paylink.webhook.WebhookEventType; import com.getpayin.paylink.webhook.Webhooks; import com.google.gson.JsonObject; import java.util.ArrayList; @@ -104,20 +105,97 @@ void rejectsInvalidJson() { assertThrows(PaylinkException.class, () -> webhooks.verify("{not json")); } + /** + * Signs a payload the way the server signs one: the always-signed four, then whichever + * optional block the payload carries, each gated on its own leading field so that + * {@code external_reference} is signed at the position the block that introduced it gives it. + */ + @Test + void verifiesCardTokenCreatedAndExposesTheSavedCard() { + JsonObject payload = cardTokenCreated(); + sign(payload, HASH); + + WebhookEvent event = webhooks.verify(payload.toString()); + assertEquals(WebhookEventType.CARD_TOKEN_CREATED, event.event()); + assertEquals("TKZ-4f21", event.tokenizationId()); + assertEquals("CRD-9a07", event.cardToken()); + assertEquals("VISA", event.cardBrand()); + assertEquals("4242", event.cardLast4()); + assertEquals("12", event.cardExpMonth()); + assertEquals("2029", event.cardExpYear()); + assertEquals("cust-42", event.externalReference()); + } + + @Test + void verifiesCardTokenFailedWhichCarriesNoCard() { + JsonObject payload = new JsonObject(); + payload.addProperty("event", "card_token.failed"); + payload.addProperty("success", 0); + payload.addProperty("invoice_id", 7782); + payload.addProperty("invoice_status", "UNPAID"); + payload.addProperty("message", "The card could not be stored for future payments."); + payload.addProperty("tokenization_id", "TKZ-4f22"); + payload.addProperty("external_reference", "cust-43"); + sign(payload, HASH); + + WebhookEvent event = webhooks.verify(payload.toString()); + assertEquals(WebhookEventType.CARD_TOKEN_FAILED, event.event()); + assertFalse(event.success()); + assertEquals("TKZ-4f22", event.tokenizationId()); + assertNull(event.cardToken()); + } + + @Test + void rejectsATamperedCard() { + JsonObject payload = cardTokenCreated(); + sign(payload, HASH); + payload.addProperty("card_last4", "1111"); + + assertFalse(webhooks.isValid(payload.toString())); + } + private static void sign(JsonObject payload, String hashToken) { - List values = new ArrayList<>(); - values.add(wire(payload, "success")); - values.add(wire(payload, "invoice_id")); - values.add(wire(payload, "invoice_status")); - values.add(wire(payload, "message")); - for (String key : List.of("mandate_id", "external_reference", "subscription_status")) { - if (payload.has(key)) { - values.add(wire(payload, key)); + List keys = new ArrayList<>(List.of("success", "invoice_id", "invoice_status", "message")); + List> blocks = List.of( + List.of("mandate_id", "external_reference", "subscription_status"), + List.of("tokenization_id", "external_reference", "card_token", "card_brand", + "card_last4", "card_exp_month", "card_exp_year")); + + for (List block : blocks) { + if (!payload.has(block.get(0))) { + continue; + } + for (String key : block) { + if (payload.has(key) && !keys.contains(key)) { + keys.add(key); + } } } + + List values = new ArrayList<>(); + for (String key : keys) { + values.add(wire(payload, key)); + } payload.addProperty("signature", Signature.build(values, hashToken)); } + private static JsonObject cardTokenCreated() { + JsonObject payload = new JsonObject(); + payload.addProperty("event", "card_token.created"); + payload.addProperty("success", 1); + payload.addProperty("invoice_id", 7781); + payload.addProperty("invoice_status", "REVERSED"); + payload.addProperty("message", "Card stored for future payments."); + payload.addProperty("tokenization_id", "TKZ-4f21"); + payload.addProperty("external_reference", "cust-42"); + payload.addProperty("card_token", "CRD-9a07"); + payload.addProperty("card_brand", "VISA"); + payload.addProperty("card_last4", "4242"); + payload.addProperty("card_exp_month", "12"); + payload.addProperty("card_exp_year", "2029"); + return payload; + } + private static String wire(JsonObject payload, String name) { if (!payload.has(name) || payload.get(name).isJsonNull()) { return ""; diff --git a/paylink-core/src/test/resources/golden-signatures.json b/paylink-core/src/test/resources/golden-signatures.json index ee98469..ec05704 100644 --- a/paylink-core/src/test/resources/golden-signatures.json +++ b/paylink-core/src/test/resources/golden-signatures.json @@ -414,6 +414,66 @@ ], "hashToken": "test_hash_token_abc123", "expected": "rk5BFKdp6JRLCX70/iPThwaybLuHV9t/AXaBRPA/J2E=" + }, + { + "name": "webhook card_token.created (card vaulted)", + "endpoint": "WEBHOOK", + "input": { + "event": "card_token.created", + "event_triggered_at": "2026-11-18T09:15:00+02:00", + "timezone": "EET", + "success": 1, + "invoice_id": 7781, + "invoice_status": "REVERSED", + "message": "Card stored for future payments.", + "tokenization_id": "TKZ-4f21", + "external_reference": "cust-42", + "card_token": "CRD-9a07", + "card_brand": "VISA", + "card_last4": "4242", + "card_exp_month": "12", + "card_exp_year": "2029" + }, + "values": [ + "1", + "7781", + "REVERSED", + "Card stored for future payments.", + "TKZ-4f21", + "cust-42", + "CRD-9a07", + "VISA", + "4242", + "12", + "2029" + ], + "hashToken": "test_hash_token_abc123", + "expected": "07XJec3X2wXLRX0S5ybJzaXv4oLCjEyY/WqomIAqi6o=" + }, + { + "name": "webhook card_token.failed (no card vaulted)", + "endpoint": "WEBHOOK", + "input": { + "event": "card_token.failed", + "event_triggered_at": "2026-11-18T09:16:00+02:00", + "timezone": "EET", + "success": 0, + "invoice_id": 7782, + "invoice_status": "UNPAID", + "message": "The card could not be stored for future payments.", + "tokenization_id": "TKZ-4f22", + "external_reference": "cust-43" + }, + "values": [ + "0", + "7782", + "UNPAID", + "The card could not be stored for future payments.", + "TKZ-4f22", + "cust-43" + ], + "hashToken": "test_hash_token_abc123", + "expected": "Fm/7wiUagH2Q82ld+dI63zSM8rkGQkQ0GXf4RAdTb/w=" } ] } diff --git a/paylink-spring-boot-starter/pom.xml b/paylink-spring-boot-starter/pom.xml index 8090f51..4d62586 100644 --- a/paylink-spring-boot-starter/pom.xml +++ b/paylink-spring-boot-starter/pom.xml @@ -7,7 +7,7 @@ com.getpayin.paylink paylink-parent - 0.2.0 + 0.3.0 paylink-spring-boot-starter @@ -18,7 +18,7 @@ com.getpayin.paylink paylink-core - 0.2.0 + 0.3.0 diff --git a/pom.xml b/pom.xml index 52f92b0..cada5e7 100644 --- a/pom.xml +++ b/pom.xml @@ -6,7 +6,7 @@ com.getpayin.paylink paylink-parent - 0.2.0 + 0.3.0 pom PayLink Java SDK (parent)