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)