Skip to content

Get Card Verification Contacts ​

GET /openapi/v2/cards/{cardId}/3ds-contact

Uses existing OpenAPI signing. cardId is the card identifier returned by card queries, not a full card number or database primary key. Only cards owned by the credential tenant are accessible.

Only supported cards expose EMAIL / PHONE actions. An unsupported card returns deliveryMode=UNSUPPORTED and an empty action list. No confirmed contact means null; the account email is not used as a fallback. When an update is pending, this query reads the channel and automatically confirms the original operation if the actual contact matches the requested value. With no pending update, it reads local records only.

Response data ​

FieldTypeDescription
providerNamestringChannel identifier for display; do not use for routing or capability checks.
deliveryModestringPROVIDER: channel-managed contacts; UNSUPPORTED: editing unavailable.
emailMaskedstring/nullConfirmed masked email.
phoneMaskedstring/nullConfirmed masked phone.
versionintegerIncremented after each confirmed update.
supportedActionsstring[]Available EMAIL / PHONE actions; empty when unsupported.
pendingbooleanWhether an unresolved update blocks further changes.
operationsarrayLatest 20 operations, using the fields below.

Operation fields ​

For updates these are the fields of data; for queries they are operations[].

FieldTypeDescription
operationNostringPlatform operation identifier.
requestNostringCaller idempotency key.
fieldstringEMAIL or PHONE.
targetMaskedstringMasked requested contact.
statusstringUNKNOWN, ACCEPTED, CONFIRMED, FAILED.
providerCodestring/nullSafe channel result code, nullable.
createdAtstringCreation time.
updatedAtstringUpdate time.

Status and retries ​

  • The outer code=200 means the platform handled the request, not that the contact is effective.
  • UNKNOWN: submission may still be in flight or its result is uncertain. ACCEPTED: channel accepted the update, effectiveness is not confirmed. Both block other updates to this card.
  • CONFIRMED: the platform verified external evidence that the update took effect. FAILED: definitive rejection or externally verified failure. Either permits a new update.
  • Same requestNo and content returns the existing operation; changed content returns UCARD_REQUEST_CONFLICT. Do not change keys to bypass an unresolved result. Query the existing record to trigger automatic verification. Contact platform support if the result remains unresolved; OpenAPI has no manual resolve endpoint.
  • Unsupported edits return UCARD_CONTACT_UNSUPPORTED; pending operations return UCARD_CONTACT_PENDING; invalid data returns UCARD_CONTACT_INVALID. These identifiers appear in msg, not as a replacement for the outer numeric code.

Automatic verification ​

An ACCEPTED operation is eligible immediately. An UNKNOWN operation becomes eligible 120 seconds after creation to protect a submission that may still be in flight. A matching query returns the refreshed masked contact, an incremented version, and CONFIRMED on the original operation; pending=false when no other update remains unresolved.

A missing or masked channel value, a mismatch, a query error, or a timeout keeps the current confirmed value and pending status. Query again later; a timeout alone does not mean failure. Each eligible query makes at most one read request with a timeout capped at 10 seconds. It never resends the contact update. A confirmed setting does not prove that a verification message was delivered.