From a96c45e9fef81487ad924f164df9eb1bf431e196 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=AF=85=E5=9F=8E?= Date: Mon, 2 Nov 2026 11:22:15 +0800 Subject: [PATCH] feat(notify): add card transaction event callback model --- .../AlipayCardTransactionEventNotify.java | 131 +++++++++++++++ .../AlipayCardTransactionEventNotifyTest.java | 64 ++++++++ .../card-transaction-event-notify.json | 154 ++++++++++++++++++ 3 files changed, 349 insertions(+) create mode 100644 src/main/java/com/alipay/global/api/request/ams/notify/AlipayCardTransactionEventNotify.java create mode 100644 src/test/java/com/alipay/global/api/request/ams/notify/AlipayCardTransactionEventNotifyTest.java create mode 100644 src/test/resources/card-transaction-event-notify.json diff --git a/src/main/java/com/alipay/global/api/request/ams/notify/AlipayCardTransactionEventNotify.java b/src/main/java/com/alipay/global/api/request/ams/notify/AlipayCardTransactionEventNotify.java new file mode 100644 index 00000000..ae489007 --- /dev/null +++ b/src/main/java/com/alipay/global/api/request/ams/notify/AlipayCardTransactionEventNotify.java @@ -0,0 +1,131 @@ +package com.alipay.global.api.request.ams.notify; + +import com.alipay.global.api.model.ams.Amount; +import com.alipay.global.api.model.ams.EventMerchantInfo; +import java.util.Map; +import lombok.AllArgsConstructor; +import lombok.Data; +import lombok.NoArgsConstructor; + +/** + * One flat ABA VCC card transaction event callback (notification profile v2.1, document v2.13). + * Verify the raw-body signature before parsing. Durable acceptance and eventId deduplication belong + * to the merchant callback handler. Amount values remain quoted minor-unit strings (up to 20 digits). + */ +@Data +@AllArgsConstructor +@NoArgsConstructor +public class AlipayCardTransactionEventNotify { + + /** Stable event ID and the only callback idempotency key. Required; maximum 64 characters. */ + private String eventId; + + /** Spend-group ID shared with inquiry. Required; maximum 64 characters. */ + private String lifecycleId; + + /** + * Required event type: AUTH, AUTH_CANCEL, CAPTURE, REFUND, CHARGEBACK or REPAYMENT. Preserve + * unknown future values. + */ + private String eventType; + + /** + * Optional ISO 8601 time of the channel-correlated authorization, maximum 32 characters. Omitted + * for AUTH or when unavailable; never inferred from transactionTime or authExpireTime. + */ + private String authTime; + + /** + * Optional ISO 8601 authorization expiry time, maximum 32 characters. Sent only for AUTH when + * available. + */ + private String authExpireTime; + + /** Optional AUTH or PRE_AUTH, maximum 32 characters. Sent only for AUTH when available. */ + private String authType; + + /** Optional network approval code, maximum 64 characters. Sent only for AUTH when available. */ + private String authCode; + + /** + * Optional Antom-normalized failure code, maximum 64 characters. Sent only for FAIL when a + * mapped code exists. + */ + private String failureReason; + + /** + * Required terminal status: SUCCESS or FAIL. CAPTURE is SUCCESS-only. The accepted status never + * changes. + */ + private String status; + + /** + * ANTOM_BIZ_ACCOUNT or ANTOM_FUND_ACCOUNT, maximum 32 characters. Required with a directional + * amount; CAPTURE sends ANTOM_BIZ_ACCOUNT. + */ + private String balanceType; + + /** Required business-event time in ISO 8601 format with timezone; maximum 32 characters. */ + private String transactionTime; + + /** + * Required CARD_PAYMENT for AUTH, CAPTURE and REPAYMENT, or CARD_REFUND for AUTH_CANCEL, REFUND + * and CHARGEBACK. + */ + private String billType; + + /** + * Required for successful AUTH, CAPTURE and REPAYMENT. CAPTURE carries value "0" and billing + * currency, not another debit; omitted otherwise. + */ + private Amount outAmount; + + /** + * Optional billing-currency inflow for successful AUTH_CANCEL, REFUND or CHARGEBACK when + * available. Omitted for CAPTURE. + */ + private Amount inAmount; + + /** + * Optional BASE/QUOTE currency pair, maximum 8 characters. Sent with exchangeRate for a cross- + * currency transaction when both are available. + */ + private String exchangeCurrencyPair; + + /** + * Optional positive quoted decimal string, maximum 32 characters. One major BASE unit equals + * this many QUOTE units; paired with exchangeCurrencyPair. + */ + private String exchangeRate; + + /** + * Required current-event amount in original transaction currency. For CAPTURE this is the + * captured amount, not the zero additional outflow. + */ + private Amount transactionAmount; + + /** Required merchant-owned card asset ID; maximum 32 characters. */ + private String assetId; + + /** Optional PCI-safe card mask exposing at most the last four digits; maximum 32 characters. */ + private String maskedCardNo; + + /** + * Optional original-transaction program code matching ^[A-Z0-9]{3}$. Extensible string, not a + * fixed enum or rebate rate; later card-profile changes do not rewrite it. + */ + private String cardProduct; + + /** + * Optional approved merchant context. Name maximum 256 characters, region exactly 2 and mcc + * exactly 4; parent omitted when no child is available. + */ + private EventMerchantInfo merchantInfo; + + /** + * Optional approved context: at most 30 entries, keys at most 32 characters, values at most 128 + * and serialized JSON at most 3096. No key is approved in notification profile v2.1, so it is + * omitted. + */ + private Map metadata; +} diff --git a/src/test/java/com/alipay/global/api/request/ams/notify/AlipayCardTransactionEventNotifyTest.java b/src/test/java/com/alipay/global/api/request/ams/notify/AlipayCardTransactionEventNotifyTest.java new file mode 100644 index 00000000..31a7c5ec --- /dev/null +++ b/src/test/java/com/alipay/global/api/request/ams/notify/AlipayCardTransactionEventNotifyTest.java @@ -0,0 +1,64 @@ +package com.alipay.global.api.request.ams.notify; + +import com.alipay.global.api.tools.JsonUtil; +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ObjectNode; +import java.io.InputStream; +import java.util.Iterator; +import org.junit.Test; +import static org.junit.Assert.*; + +public class AlipayCardTransactionEventNotifyTest { + private final ObjectMapper mapper = new ObjectMapper(); + + private JsonNode withoutNulls(JsonNode value) { + if (value.isObject()) { + ObjectNode result = mapper.createObjectNode(); + Iterator keys = value.fieldNames(); + while (keys.hasNext()) { + String key = keys.next(); + if (!value.get(key).isNull()) result.set(key, withoutNulls(value.get(key))); + } + return result; + } + return value; + } + + @Test public void parsesEveryDocumentedFieldWithoutAnEnvelope() throws Exception { + assertEquals(22, AlipayCardTransactionEventNotify.class.getDeclaredFields().length); + try (InputStream stream = getClass().getResourceAsStream("/card-transaction-event-notify.json")) { + assertNotNull(stream); + for (JsonNode fixture : mapper.readTree(stream)) { + ObjectNode body = fixture.get("body").deepCopy(); + body.putObject("futureField").put("ignored", true); + AlipayCardTransactionEventNotify notify = + JsonUtil.fromJson(body.toString(), AlipayCardTransactionEventNotify.class); + assertEquals(fixture.get("name").asText(), withoutNulls(fixture.get("body")), + mapper.readTree(JsonUtil.toJson(notify))); + assertEquals(fixture.get("body").get("eventId").asText(), notify.getEventId()); + } + } + } + + @Test public void preservesCaptureZeroAndAuthorizationCorrelationTime() throws Exception { + try (InputStream stream = getClass().getResourceAsStream("/card-transaction-event-notify.json")) { + JsonNode fixtures = mapper.readTree(stream); + AlipayCardTransactionEventNotify auth = + JsonUtil.fromJson(fixtures.get(0).get("body").toString(), AlipayCardTransactionEventNotify.class); + assertNull(auth.getAuthTime()); + AlipayCardTransactionEventNotify capture = + JsonUtil.fromJson(fixtures.get(1).get("body").toString(), AlipayCardTransactionEventNotify.class); + assertEquals("0", capture.getOutAmount().getValue()); + assertEquals("USD", capture.getOutAmount().getCurrency()); + assertEquals("30000", capture.getTransactionAmount().getValue()); + assertEquals("2026-07-09T10:35:10+00:00", capture.getAuthTime()); + assertNull(capture.getInAmount()); + assertEquals("ANTOM_BIZ_ACCOUNT", capture.getBalanceType()); + } + AlipayCardTransactionEventNotify empty = new AlipayCardTransactionEventNotify(); + empty.setEventId("setter"); + assertEquals("setter", empty.getEventId()); + assertNull(empty.getMetadata()); + } +} diff --git a/src/test/resources/card-transaction-event-notify.json b/src/test/resources/card-transaction-event-notify.json new file mode 100644 index 00000000..86eb53fa --- /dev/null +++ b/src/test/resources/card-transaction-event-notify.json @@ -0,0 +1,154 @@ +[ + { + "name": "auth", + "body": { + "assetId": "example_asset_****", + "authCode": "00****", + "authExpireTime": "2026-07-18T03:35:10-07:00", + "authType": "AUTH", + "balanceType": "ANTOM_BIZ_ACCOUNT", + "billType": "CARD_PAYMENT", + "cardProduct": "MTA", + "eventId": "example_auth_event_****", + "eventType": "AUTH", + "exchangeCurrencyPair": "USD/CAD", + "exchangeRate": "1.36734", + "maskedCardNo": "****7952", + "merchantInfo": { + "mcc": "7695", + "name": "Example Merchant", + "region": "US" + }, + "lifecycleId": "example_auth_lifecycle_****", + "outAmount": { + "currency": "USD", + "value": "10366" + }, + "status": "SUCCESS", + "transactionAmount": { + "currency": "CAD", + "value": "14174" + }, + "transactionTime": "2026-07-11T03:35:10-07:00" + } + }, + { + "name": "capture", + "body": { + "assetId": "example_asset_****", + "authTime": "2026-07-09T10:35:10+00:00", + "balanceType": "ANTOM_BIZ_ACCOUNT", + "billType": "CARD_PAYMENT", + "cardProduct": "MTA", + "eventId": "example_capture_event_****", + "eventType": "CAPTURE", + "lifecycleId": "example_capture_lifecycle_****", + "outAmount": { + "currency": "USD", + "value": "0" + }, + "status": "SUCCESS", + "transactionAmount": { + "currency": "USD", + "value": "30000" + }, + "transactionTime": "2026-07-10T00:02:15-07:00" + } + }, + { + "name": "refund", + "body": { + "eventId": "refund-event", + "lifecycleId": "spend-1", + "eventType": "REFUND", + "authTime": "2026-07-09T10:35:10-07:00", + "status": "SUCCESS", + "balanceType": "ANTOM_FUND_ACCOUNT", + "transactionTime": "2026-07-12T10:35:10+08:00", + "billType": "CARD_REFUND", + "inAmount": { + "value": "99999999999999999999", + "currency": "USD" + }, + "transactionAmount": { + "value": "99999999999999999999", + "currency": "USD" + }, + "assetId": "card-1", + "merchantInfo": { + "name": "商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商商", + "region": "US", + "mcc": "0001" + } + } + }, + { + "name": "failure", + "body": { + "eventId": "failed-event", + "lifecycleId": "spend-1", + "eventType": "AUTH", + "status": "FAIL", + "failureReason": "CARD_BALANCE_NOT_ENOUGH", + "transactionTime": "2026-07-12T10:35:10+00:00", + "billType": "CARD_PAYMENT", + "transactionAmount": { + "value": "105", + "currency": "USD" + }, + "assetId": "card-1" + } + }, + { + "name": "future_values_transport_only", + "body": { + "eventId": "future-event", + "lifecycleId": "spend-1", + "eventType": "FUTURE_EVENT", + "status": "SUCCESS", + "authType": "FUTURE_AUTH", + "balanceType": "FUTURE_BALANCE", + "transactionTime": "2026-07-12T10:35:10+00:00", + "billType": "FUTURE_BILL", + "outAmount": { + "value": "0", + "currency": "USD" + }, + "transactionAmount": { + "value": "105", + "currency": "USD" + }, + "cardProduct": "Z9X", + "assetId": "card-1", + "exchangeCurrencyPair": "USD/CAD", + "exchangeRate": "1.00000000000000000001", + "metadata": { + "futureKey": "0", + "unicode": "中文", + "empty": "" + } + } + }, + { + "name": "null_optionals_tolerated", + "body": { + "eventId": "null-event", + "lifecycleId": "spend-1", + "eventType": "AUTH", + "status": "FAIL", + "transactionTime": "2026-07-12T10:35:10+00:00", + "billType": "CARD_PAYMENT", + "transactionAmount": { + "value": "105", + "currency": "USD" + }, + "assetId": "card-1", + "authTime": null, + "cardProduct": null, + "outAmount": null, + "inAmount": null, + "merchantInfo": null, + "metadata": null + } + } +]