Skip to content
Merged
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
Original file line number Diff line number Diff line change
@@ -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<String, String> metadata;
}
Original file line number Diff line number Diff line change
@@ -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<String> 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());
}
}
154 changes: 154 additions & 0 deletions src/test/resources/card-transaction-event-notify.json
Original file line number Diff line number Diff line change
@@ -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
}
}
]
Loading