Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion paylink-core/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<parent>
<groupId>com.getpayin.paylink</groupId>
<artifactId>paylink-parent</artifactId>
<version>0.2.0</version>
<version>0.3.0</version>
</parent>

<artifactId>paylink-core</artifactId>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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<String> ALWAYS_SIGNED = List.of("success", "invoice_id", "invoice_status", "message");

private static final List<String> 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<String> MANDATE_SIGNED = List.of("mandate_id", "external_reference", "subscription_status");

/**
* The fields a card-token event adds, in the order the server adds them.
*
* <p>{@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.
*
* <p>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<String> TOKENIZATION_SIGNED = List.of(
"tokenization_id", "external_reference", "card_token", "card_brand", "card_last4",
"card_exp_month", "card_exp_year");

private final PaylinkConfig config;

Expand Down Expand Up @@ -69,16 +86,32 @@ public boolean isValid(String payload, String hashToken) {
}
}

/**
* Rebuilds the expected signature the way the server assembles it.
*
* <p>{@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<String> keys = new ArrayList<>(ALWAYS_SIGNED);
for (List<String> 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<String> 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);
}

Expand Down Expand Up @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
* <p>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,
Expand All @@ -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<String, Object> 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);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
}
Expand Down
94 changes: 86 additions & 8 deletions paylink-core/src/test/java/com/getpayin/paylink/WebhookTest.java
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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<String> 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<String> keys = new ArrayList<>(List.of("success", "invoice_id", "invoice_status", "message"));
List<List<String>> 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<String> block : blocks) {
if (!payload.has(block.get(0))) {
continue;
}
for (String key : block) {
if (payload.has(key) && !keys.contains(key)) {
keys.add(key);
}
}
}

List<String> 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 "";
Expand Down
60 changes: 60 additions & 0 deletions paylink-core/src/test/resources/golden-signatures.json
Original file line number Diff line number Diff line change
Expand Up @@ -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="
}
]
}
4 changes: 2 additions & 2 deletions paylink-spring-boot-starter/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<parent>
<groupId>com.getpayin.paylink</groupId>
<artifactId>paylink-parent</artifactId>
<version>0.2.0</version>
<version>0.3.0</version>
</parent>

<artifactId>paylink-spring-boot-starter</artifactId>
Expand All @@ -18,7 +18,7 @@
<dependency>
<groupId>com.getpayin.paylink</groupId>
<artifactId>paylink-core</artifactId>
<version>0.2.0</version>
<version>0.3.0</version>
</dependency>

<dependency>
Expand Down
2 changes: 1 addition & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

<groupId>com.getpayin.paylink</groupId>
<artifactId>paylink-parent</artifactId>
<version>0.2.0</version>
<version>0.3.0</version>
<packaging>pom</packaging>

<name>PayLink Java SDK (parent)</name>
Expand Down
Loading