Cards

Simulate 3DS authentication

Simulate a 3DS authentication attempt for a sandbox card and return the resulting 3DS attempt.

Set realtime_decision to supply the authentication decision without calling your endpoint. When it is omitted, Column sends a 3DS authentication decision request to your endpoint subscribed to decision.issuing.card_authentication; if no endpoint is subscribed, the simulator creates an OTP challenge.

  • frictionless_approve authenticates the attempt and fires issuing.3ds.authentication_completed.
  • challenge starts an OTP challenge and fires issuing.3ds.otp_generated. Finish it with the complete 3DS challenge endpoint.
  • decline_authentication rejects the attempt and fires issuing.3ds.authentication_completed.
post/simulate/issuing/cards/{card_id}/threeds/challenge

Request

  • Base URL: https://api.column.com
  • URL: https://api.column.com/simulate/issuing/cards/{card_id}/threeds/challenge
  • Auth: HTTP basic

Path parameters

card_idstring required

Request body

amountinteger required

Transaction amount in the smallest unit of the currency (e.g., cents for USD).

currencystring required

ISO 4217 currency code for the transaction.

decline_reason'suspected_fraud' | 'transaction_not_permitted' nullable

The simulated decline reason. Only meaningful when realtime_decision is decline_authentication; when omitted, Column defaults to suspected_fraud.

merchant_category_codestring nullable

Optional merchant category code (ISO 18245 MCC) to put on the simulated 3DS attempt and on the decision request, so that authentication rules that depend on the merchant category can be exercised in sandbox.

merchant_country_codestring nullable

Optional merchant country, ISO 3166-1 alpha-2, to put on the simulated 3DS attempt and on the decision request.

merchant_namestring nullable

Optional merchant name to put on the simulated 3DS attempt and on the decision.issuing.card_authentication request. Omitted, it stays null.

merchant_urlstring nullable

Optional merchant URL to put on the simulated 3DS attempt and on the decision request.

message_category'payment' | 'non_payment' nullable

Optional 3DS message category to put on the decision request: payment or non_payment (for example, adding a card to a merchant's file). Omitted, it stays null.

realtime_decision'frictionless_approve' | 'challenge' | 'decline_authentication' nullable

Overrides the real-time 3DS decisioning webhook response for this simulated authentication. When omitted and the platform has a webhook endpoint subscribed to decision.issuing.card_authentication, the webhook is actually invoked.

Example request

{
  "amount": 1000,
  "currency": "USD",
  "merchant_category_code": "5812",
  "merchant_country_code": "CA",
  "merchant_name": "BLUE BOTTLE COFFEE",
  "merchant_url": "https://bluebottlecoffee.com"
}

Response

Successful response

acs_transaction_idstring required

The Access Control Server (ACS) transaction identifier

amountinteger required

The transaction amount in the smallest unit of the currency (e.g., cents for USD)

attempt_countinteger required

The number of authentication attempts made

attempt_status'rejected' | 'presented' | 'challenged' | 'authenticated' | 'associated' required

The status of a 3DS authentication attempt

card_account_idstring required

The card account associated with this 3DS attempt

card_idstring required

The card associated with this 3DS attempt

challenged_atstring date-time nullable

Timestamp when the challenge was presented to the cardholder

challenges_presentedstring[] nullable

List of challenge types that were presented to the cardholder

chosen_challenge'frictionless' | 'attempts' | 'otp' | 'biometric' | 'external'

The type of challenge used in 3DS authentication

completed_atstring date-time nullable

Timestamp when the authentication was completed

created_atstring date-time required

Timestamp when the 3DS attempt was created

currencystring required

The ISO 4217 currency code for the transaction

ds_transaction_idstring required

The Directory Server (DS) transaction identifier

idstring required

Unique identifier for the 3DS attempt

merchant_category_codestring nullable

The Merchant Category Code (MCC)

merchant_country_codestring nullable

The ISO 3166-1 alpha-2 country code of the merchant

merchant_namestring nullable

The name of the merchant

merchant_urlstring nullable

The URL of the merchant

otp_valuestring nullable

The one-time password value used for authentication

outcome_reason'frictionless' | 'challenged_accepted' | 'attempts' | 'card_account_status' | 'failed_challenge' | 'rule_rejected' | 'error'

The reason for the 3DS authentication outcome

realtime_decision'frictionless_approve' | 'challenge' | 'decline_authentication' nullable

The platform's real-time 3DS authentication decision. Only set when the platform uses real-time 3DS decisioning

three_ds_message_versionstring required

The 3D Secure protocol message version

updated_atstring date-time required

Timestamp when the 3DS attempt was last updated

Example response

{
  "acs_transaction_id": "9a2c4e6b-3f1d-4b8a-a5e7-1c3d5f7b9e20",
  "amount": 12345,
  "attempt_count": 1,
  "attempt_status": "authenticated",
  "card_account_id": "cacc_2x8gszy5folpA9s0TOCseE9ABDM",
  "card_id": "card_2x8gszy5folpA9s0TOCseE9ABDM",
  "challenges_presented": [
    "otp"
  ],
  "chosen_challenge": "otp",
  "currency": "USD",
  "ds_transaction_id": "4f8b2c1e-9a3d-4e7b-8c6f-2d1a5b9e3c70",
  "id": "tdsa_2x8gszy5folpA9s0TOCseE9ABDM",
  "merchant_category_code": "5411",
  "merchant_country_code": "US",
  "merchant_name": "Yellen Cocktails, LLC",
  "merchant_url": "https://example.com",
  "outcome_reason": "challenged_accepted",
  "three_ds_message_version": "2.3.1"
}

Changes

No recorded changes to this operation across all 1 revision of this API.