Existing time fields remain compatible, with new UTC Unix millisecond timestamps. Clients choose the display timezone.

Time and Timezones

Absolute Instants

Responses retain existing absolute-time fields, types, and meanings, while adding fields named the original field plus _ms. New values are JSON integers, with OpenAPI type integer and format int64, always measured in milliseconds: the number of milliseconds since 1970-01-01T00:00:00Z, without a regional timezone.

{
  "created_at": "2026-09-14T08:05:08.680Z",
  "created_at_ms": 1789373108680
}

The same instant is 2026-09-14 16:05:08.680 in Shanghai and 2026-09-14 08:05:08.680 in UTC. Do not add or subtract eight hours from timestamps. Format only for final display using the device or user-selected timezone. Handle daylight saving time with system timezone rules, not a fixed hourly offset substituted for a regional timezone.

This applies to objects, lists, and nested DTOs, including created_at_ms, updated_at_ms, occurred_at_ms, expires_at_ms, timeline at_ms, and exchange-rate as_of_ms. Legacy camelCase fields are not renamed; for example, createdAt maps to createdAt_ms. An existing same-name _ms field is not overwritten.

If the original value is empty or a recognized time field cannot be parsed safely, the new value is null, never 0 or the current time. ISO times with timezones support both fractional and whole seconds; precision beyond milliseconds is truncated to milliseconds. Time strings without timezone information are not arbitrarily interpreted as UTC or server-local time.

Legacy Seconds Fields

Existing numeric expired_at and expires_at fields on tokens, KYC sessions, and step-up sessions remain Unix seconds. Only their new _ms fields are converted to milliseconds. Do not change how you read the original fields. Unknown numeric units are neither inferred from digit count nor automatically multiplied by 1000.

Fields That Are Not Converted

• Date-only YYYY-MM-DD values—birth dates, ID validity dates, value dates, maturity dates, and settlement business dates—are not absolute instants. No fabricated midnight timestamp is added.
• Durations, TTLs, retry intervals, and countdown seconds are not instants; their original units remain unchanged.
• Timestamp units in request fields, JWT claims, signature headers, and signing protocols remain unchanged.
• Caller metadata, upstream original content, raw requests/responses, signing payloads, and schemas are not rewritten as business DTOs.
• Binary files, streaming responses, provider callback protocols, and internal database execution interfaces do not receive this projection.

Webhooks and Replays

New merchant webhooks receive the additional time fields before enqueueing; the final payload is then signed and sent. Retries use the same queued payload and do not regenerate times based on the current time or device timezone. Historical queued webhooks are not rewritten, avoiding changes to in-flight payloads or signing input.

API idempotent replays may add the same derived timestamps to historical JSON responses, while leaving original business fields unchanged. They neither execute the business operation again nor replace the original event time with replay time. Integrators should ignore unknown response fields and not depend on JSON property counts or byte-level ordering.

Client Display

Prefer the new _ms fields. For compatibility with older servers, fall back to parsing original ISO fields that include a timezone. iOS Unix-time constructors use seconds, so divide milliseconds by 1000 before constructing a Date. The device timezone controls clock time and daily grouping; the App language controls date wording and ordering. When the App returns to the foreground or the device timezone changes, reformat existing times without recreating business records.