Wire-contract parity: serializer, date split, payment_details discriminator, and error mapping

[tomas-amaro]

What this is

Wire-contract parity fixes for the Java SDK, derived from the language-neutral
Riskified contract corpus and audited against the C# reference implementation
(Riskified/sdk_net @ 9165cf5). Two commits, production source plus regression
tests.

Changes

Serializer parity

• dropoff_latitude — RideLineItem.dropoffLatitude has no @SerializedName, so Gson derives dropoff_latitude, which is correct: both OpenAPI specs declare that spelling, with a description and an example. An earlier revision of this branch pinned the transposed dropoff_latitiude instead, on the strength of the contract corpus — which had inferred the misspelling was the live wire name purely from the fact that the C# SDK sends it (RideTicketLineItem.cs:100). That inference was wrong, and the pin has been reverted: the transposed spelling appears in neither spec, occurs exactly once in all of sdk_net with no test covering it, and sits beside a correctly spelled pickup_latitude and dropoff_longitude in the same class. It is a defect in the C# SDK, not the contract. The test now asserts dropoff_latitude is emitted and dropoff_latitiude is not, guarded in both directions. The other 19 RideLineItem fields derive correctly and are locked by a test. The corpus has been corrected in Riskified/sdk-orchestrator.
• HMAC key charset — SHA256Handler used authKey.getBytes(), the platform default, making the signature depend on a JVM locale setting. Pinned to UTF-8.
• The date split — the contract splits 25 offset-bearing date fields from 13 naive ones, following no principle a single adapter can express. The 13 naive fields now carry @JsonAdapter(NaiveDateTypeAdapter.class); everything else keeps the offset format. Both formats render in UTC with Locale.US, so the same Date no longer serializes differently on two machines — and neither does the HMAC computed over those bytes.
• The method discriminator — payment_details carries no type discriminator on the wire; the variant is expressed by which keys are present. RuntimeTypeAdapterFactory injected a method key whose values disagreed with the payment_type emitted alongside. Replaced with PaymentDetailsAdapterFactory, which dispatches on runtime type and emits no label. The replacement is necessary rather than cosmetic: BaseOrder/DecisionOrder declare the field as List<? extends IPaymentDetails>, and Gson's runtime-type promotion fires only for a Class element type, not a WildcardType — simply unregistering the old factory serializes every element as {}.
• KycDetails.updateAt derived update_at; the contract key is updated_at (KycDetails.cs:18), so KYC update timestamps were silently not arriving. Pinned with @SerializedName rather than renaming the field, which would break every caller of getUpdateAt()/setUpdateAt().
• Customer.verifiedEmailAt / Customer.firstPurchaseAt were absent from the Java model entirely (Customer.cs:143, :167). Added as offset-bearing boxed Date, omitted when null. The date split now covers 25/25 offset-bearing fields.

Error mapping

• The default: branch rewrote every unmatched status to 500 "Contact Riskified support" and discarded the body, so a 502, a 503 and a genuine 500 were indistinguishable. Statuses are now reported as themselves through a new RiskifiedHttpException, which extends HttpResponseException — existing catch blocks and getStatusCode() are unaffected — and carries statusText, the raw body, and the parsed error as separate structured fields that logging can redact.
• The checkout path no longer dereferences getError().getMessage() before establishing that the body parsed as that shape. Six of the seven documented error shapes previously raised a NullPointerException in place of the HTTP error.
• postOrder read the response body with no charset. httpclient resolves UTF-8 for application/json, but ISO-8859-1 for text/html, text/plain, and a body with no Content-Type at all — exactly the 502/503-from-a-proxy case above. Now passes UTF-8 explicitly, matching postCheckoutOrder.
• Response.getReceived() unboxed a null Integer, raising NullPointerException on every response that omits received — which is every error response. It now returns 0, keeping the primitive return type so existing callers still compile; getReceivedOrNull() exposes the absent/zero distinction.

Deliberately unchanged

Null-handling and the 30 always-emitted defaults (open question in the corpus), the Accept header, User-Agent, the Version header, and the webhook receiver. StripePaymentDetails stays in place, minus the method key.

A before/after payload diff confirms the only key-set changes are the dropoff_latitiude rename and the removal of method.

Reviewer notes

• Public API surface is preserved throughout — no method name or signature moved, and the two behavioural changes to existing methods (getReceived() returning 0, unmatched statuses no longer collapsing to 500) are called out above.
• Also audited: all 28 non-derivable wire names in the corpus model catalog against their Java fields. 26 are correct. The other two — group_founder_order_id (OrderBase.cs:188) and buyer_anonymous_id (Customer.cs:155) — are not modelled in Java at all. Reported here, not fixed.
• Branch is based on d02605f and is one commit behind master (fa18fe0). It merges cleanly.
• The test suite was not executed in the environment where these commits were authored; please let CI be the judge.

🤖 Generated with Claude Code