# POST /api/transactions/three-d-secure/authenticate

Authenticate a cardholder with 3-D Secure for a card payment you are about to create.

Sends the card, the purchase amount and the cardholder's browser details to the merchant's
3-D Secure provider and returns the issuer's answer. A decided answer carries
`authenticated`; an issuer that wants to challenge the cardholder returns a
`challenge` block instead. Present it by posting an HTML form to `challenge.acsUrl`
from a window of `challenge.challengeWindowSize`, with `creq` set to
`challenge.encodedChallengeRequest` and, when present, `threeDSSessionData` set to
`challenge.sessionData`. The issuer returns the cardholder to `challengeReturnUrl`
when the challenge ends.

Then create the transaction with `threeDSecure.threeDSServerTransactionId` set to the
returned id. The gateway reads the decided authentication from the provider when the
transaction is created; the authentication value is never returned here and never trusted
from a request. Create the transaction within thirty minutes, for the same amount and with the
same card the authentication was run for. Each authentication backs one transaction.

The card number and expiration are sent to the provider and are never stored, logged or
audited; the gateway keeps only a keyed fingerprint of the card number, to check the card the
transaction charges. A merchant with no 3-D Secure provider configured is refused with 403
`Transactions:ThreeDSecureNotAvailableForMerchant`; a provider that refuses or cannot
authenticate answers 400 `Transactions:ThreeDSecureAuthenticationFailed`, with the
provider's own code in the error data.

**Operation ID:** `threeDSecureAuthenticate`

## Authorization

Requires: Transactions.Payments.Create, merchant scope.

Requires API key scope: `transactions:write`

Required permissions:
- `Transactions.Payments.Create`

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| suppressNulls | query | no | boolean | If true, omit properties with null values. |

## Request Body

The card, purchase and browser details to authenticate.

**Content type:** `application/json`

Schema: [`ThreeDSecureAuthenticateInputDto`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureAuthenticateInputDto.md)

Properties:
- `merchantId` (string(uuid)): The merchant the authentication is for. Optional for a credential bound to one merchant, which resolves it from the credential; required for a credential that reaches several. (nullable)
- `cardData` ([ThreeDSecureCardDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureCardDto.md)) required: The card to authenticate. The card number and expiration are required; the cardholder name, email, phone and billing address improve the issuer's risk decision and are optional. Conditional: When CardData is not null.
  Fields:
  - `cardNumber` (string) required: The card number, 12 to 19 digits, passing the Luhn check. Required. Sent to the 3-D Secure provider; never stored, logged or audited. Charge the same card when you create the transaction. (nullable)
  - `expirationMonth` (integer(int32)) required: The expiration month, 1 to 12. Required. (nullable, min 1, max 12)
  - `expirationYear` (integer(int32)) required: The four-digit expiration year. Required. The card must not be expired: it is good through the end of its expiration month. Conditional: Conditional (see validator source). (nullable, min 2000, max 2099)
  - `nameOnCard` (string): The name on the card. Optional. (nullable, max length 100)
  - `email` (string): The cardholder's email address. Optional. (nullable, max length 254)
  - `phone` (string): The cardholder's phone number. Optional. (nullable, max length 32)
  - `billingAddress` ([Address](https://devportal.signapay-sbx.winkpg.io/docs/api/models/Address.md)): The cardholder's billing address. Optional. Conditional: When BillingAddress is not null.
- `amount` (number(double)) required: The purchase amount the transaction will carry, in the transaction currency as a decimal (`42.50`, not minor units). Required, more than zero. Create the transaction for this amount. (nullable)
- `currencyCode` (string): The ISO 4217 currency code. Optional; `USD` when omitted. Card transactions are charged in `USD`, so a transaction that references an authentication run in another currency is refused when it is created. Conditional: When CurrencyCode is not empty. (nullable)
- `challengeReturnUrl` (string) required: The HTTPS URL the issuer's challenge page posts the result to once the cardholder completes it. Required. The gateway does not host the challenge; the caller does, and submits the returned `threeDSServerTransactionId` on the transaction once the challenge returns. (nullable, max length 2048)
- `challengePreference` ([ThreeDSecureChallengePreference](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureChallengePreference.md)): Whether the caller prefers a challenge, prefers none, or leaves it to the issuer. Optional. Conditional: When ChallengePreference is not null. (nullable)
  Values:
  - `NoPreference`: Let the issuer decide.
  - `NoChallengeRequested`: Ask the issuer not to challenge.
  - `ChallengeRequested`: Ask the issuer to challenge.
- `challengeWindowSize` ([ThreeDSChallengeWindowSize](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSChallengeWindowSize.md)): The size of the window the caller will present a challenge in. Optional; the issuer is told `500x600` when it is omitted. Conditional: When ChallengeWindowSize is not null. (nullable)
  Values:
  - `Size250X400`: Wire value 01: 250 x 400.
  - `Size390X400`: Wire value 02: 390 x 400.
  - `Size500X600`: Wire value 03: 500 x 600.
  - `Size600X400`: Wire value 04: 600 x 400.
  - `FullScreen`: Wire value 05: full screen.
- `browser` ([ThreeDSecureBrowserDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureBrowserDto.md)) required: The cardholder's browser, as the page that collected the card observed it. Required: the issuer's risk decision is made from it, and a browser authentication that carries none is refused by the vendor. `acceptHeader` and `userAgent` are required; send every other value the page can observe. Conditional: When Browser is not null.
  Fields:
  - `acceptHeader` (string) required: The browser's `Accept` header. (nullable, max length 2048)
  - `userAgent` (string) required: The browser's `User-Agent` header. (nullable, max length 2048)
  - `ipAddress` (string): The cardholder's IP address as the page observed it. (nullable, max length 45)
  - `language` (string): The browser language, for example `en-US`. (nullable, max length 8)
  - `colorDepth` (integer(int32)): The screen color depth in bits. (nullable)
  - `screenHeight` (integer(int32)): The screen height in pixels. (nullable)
  - `screenWidth` (integer(int32)): The screen width in pixels. (nullable)
  - `timeZoneOffsetMinutes` (integer(int32)): The offset between UTC and the browser's local time, in minutes. (nullable)
  - `javaEnabled` (boolean): Whether Java is enabled in the browser. (nullable)
  - `javaScriptEnabled` (boolean): Whether JavaScript is enabled in the browser. (nullable)

_Example: Authenticate a card_

The fields an issuer needs: the card, the amount the transaction will charge, where the issuer returns the cardholder after a challenge, and the cardholder's browser as your page observed it. Replace merchantId with your merchant's id, or omit it for a key bound to one merchant.

```json
{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe"
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "browser": {
    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
}
```

_Example: Authenticate with cardholder details and a challenge preference_

The same authentication with the cardholder's billing address and contact details, which improve the issuer's risk decision, a request that the issuer challenge the cardholder, and the window size your page will present the challenge in.

```json
{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe",
    "email": "john.doe@example.com",
    "phone": "5555550123",
    "billingAddress": {
      "address1": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701",
      "country": "US"
    }
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "challengePreference": "ChallengeRequested",
  "challengeWindowSize": "Size500X600",
  "browser": {
    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
}
```

**Content type:** `text/json`

Schema: [`ThreeDSecureAuthenticateInputDto`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureAuthenticateInputDto.md)

Properties:
- `merchantId` (string(uuid)): The merchant the authentication is for. Optional for a credential bound to one merchant, which resolves it from the credential; required for a credential that reaches several. (nullable)
- `cardData` ([ThreeDSecureCardDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureCardDto.md)) required: The card to authenticate. The card number and expiration are required; the cardholder name, email, phone and billing address improve the issuer's risk decision and are optional. Conditional: When CardData is not null.
  Fields:
  - `cardNumber` (string) required: The card number, 12 to 19 digits, passing the Luhn check. Required. Sent to the 3-D Secure provider; never stored, logged or audited. Charge the same card when you create the transaction. (nullable)
  - `expirationMonth` (integer(int32)) required: The expiration month, 1 to 12. Required. (nullable, min 1, max 12)
  - `expirationYear` (integer(int32)) required: The four-digit expiration year. Required. The card must not be expired: it is good through the end of its expiration month. Conditional: Conditional (see validator source). (nullable, min 2000, max 2099)
  - `nameOnCard` (string): The name on the card. Optional. (nullable, max length 100)
  - `email` (string): The cardholder's email address. Optional. (nullable, max length 254)
  - `phone` (string): The cardholder's phone number. Optional. (nullable, max length 32)
  - `billingAddress` ([Address](https://devportal.signapay-sbx.winkpg.io/docs/api/models/Address.md)): The cardholder's billing address. Optional. Conditional: When BillingAddress is not null.
- `amount` (number(double)) required: The purchase amount the transaction will carry, in the transaction currency as a decimal (`42.50`, not minor units). Required, more than zero. Create the transaction for this amount. (nullable)
- `currencyCode` (string): The ISO 4217 currency code. Optional; `USD` when omitted. Card transactions are charged in `USD`, so a transaction that references an authentication run in another currency is refused when it is created. Conditional: When CurrencyCode is not empty. (nullable)
- `challengeReturnUrl` (string) required: The HTTPS URL the issuer's challenge page posts the result to once the cardholder completes it. Required. The gateway does not host the challenge; the caller does, and submits the returned `threeDSServerTransactionId` on the transaction once the challenge returns. (nullable, max length 2048)
- `challengePreference` ([ThreeDSecureChallengePreference](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureChallengePreference.md)): Whether the caller prefers a challenge, prefers none, or leaves it to the issuer. Optional. Conditional: When ChallengePreference is not null. (nullable)
  Values:
  - `NoPreference`: Let the issuer decide.
  - `NoChallengeRequested`: Ask the issuer not to challenge.
  - `ChallengeRequested`: Ask the issuer to challenge.
- `challengeWindowSize` ([ThreeDSChallengeWindowSize](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSChallengeWindowSize.md)): The size of the window the caller will present a challenge in. Optional; the issuer is told `500x600` when it is omitted. Conditional: When ChallengeWindowSize is not null. (nullable)
  Values:
  - `Size250X400`: Wire value 01: 250 x 400.
  - `Size390X400`: Wire value 02: 390 x 400.
  - `Size500X600`: Wire value 03: 500 x 600.
  - `Size600X400`: Wire value 04: 600 x 400.
  - `FullScreen`: Wire value 05: full screen.
- `browser` ([ThreeDSecureBrowserDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureBrowserDto.md)) required: The cardholder's browser, as the page that collected the card observed it. Required: the issuer's risk decision is made from it, and a browser authentication that carries none is refused by the vendor. `acceptHeader` and `userAgent` are required; send every other value the page can observe. Conditional: When Browser is not null.
  Fields:
  - `acceptHeader` (string) required: The browser's `Accept` header. (nullable, max length 2048)
  - `userAgent` (string) required: The browser's `User-Agent` header. (nullable, max length 2048)
  - `ipAddress` (string): The cardholder's IP address as the page observed it. (nullable, max length 45)
  - `language` (string): The browser language, for example `en-US`. (nullable, max length 8)
  - `colorDepth` (integer(int32)): The screen color depth in bits. (nullable)
  - `screenHeight` (integer(int32)): The screen height in pixels. (nullable)
  - `screenWidth` (integer(int32)): The screen width in pixels. (nullable)
  - `timeZoneOffsetMinutes` (integer(int32)): The offset between UTC and the browser's local time, in minutes. (nullable)
  - `javaEnabled` (boolean): Whether Java is enabled in the browser. (nullable)
  - `javaScriptEnabled` (boolean): Whether JavaScript is enabled in the browser. (nullable)

_Example: Authenticate a card_

The fields an issuer needs: the card, the amount the transaction will charge, where the issuer returns the cardholder after a challenge, and the cardholder's browser as your page observed it. Replace merchantId with your merchant's id, or omit it for a key bound to one merchant.

```json
{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe"
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "browser": {
    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
}
```

_Example: Authenticate with cardholder details and a challenge preference_

The same authentication with the cardholder's billing address and contact details, which improve the issuer's risk decision, a request that the issuer challenge the cardholder, and the window size your page will present the challenge in.

```json
{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe",
    "email": "john.doe@example.com",
    "phone": "5555550123",
    "billingAddress": {
      "address1": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701",
      "country": "US"
    }
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "challengePreference": "ChallengeRequested",
  "challengeWindowSize": "Size500X600",
  "browser": {
    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
}
```

**Content type:** `application/*+json`

Schema: [`ThreeDSecureAuthenticateInputDto`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureAuthenticateInputDto.md)

Properties:
- `merchantId` (string(uuid)): The merchant the authentication is for. Optional for a credential bound to one merchant, which resolves it from the credential; required for a credential that reaches several. (nullable)
- `cardData` ([ThreeDSecureCardDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureCardDto.md)) required: The card to authenticate. The card number and expiration are required; the cardholder name, email, phone and billing address improve the issuer's risk decision and are optional. Conditional: When CardData is not null.
  Fields:
  - `cardNumber` (string) required: The card number, 12 to 19 digits, passing the Luhn check. Required. Sent to the 3-D Secure provider; never stored, logged or audited. Charge the same card when you create the transaction. (nullable)
  - `expirationMonth` (integer(int32)) required: The expiration month, 1 to 12. Required. (nullable, min 1, max 12)
  - `expirationYear` (integer(int32)) required: The four-digit expiration year. Required. The card must not be expired: it is good through the end of its expiration month. Conditional: Conditional (see validator source). (nullable, min 2000, max 2099)
  - `nameOnCard` (string): The name on the card. Optional. (nullable, max length 100)
  - `email` (string): The cardholder's email address. Optional. (nullable, max length 254)
  - `phone` (string): The cardholder's phone number. Optional. (nullable, max length 32)
  - `billingAddress` ([Address](https://devportal.signapay-sbx.winkpg.io/docs/api/models/Address.md)): The cardholder's billing address. Optional. Conditional: When BillingAddress is not null.
- `amount` (number(double)) required: The purchase amount the transaction will carry, in the transaction currency as a decimal (`42.50`, not minor units). Required, more than zero. Create the transaction for this amount. (nullable)
- `currencyCode` (string): The ISO 4217 currency code. Optional; `USD` when omitted. Card transactions are charged in `USD`, so a transaction that references an authentication run in another currency is refused when it is created. Conditional: When CurrencyCode is not empty. (nullable)
- `challengeReturnUrl` (string) required: The HTTPS URL the issuer's challenge page posts the result to once the cardholder completes it. Required. The gateway does not host the challenge; the caller does, and submits the returned `threeDSServerTransactionId` on the transaction once the challenge returns. (nullable, max length 2048)
- `challengePreference` ([ThreeDSecureChallengePreference](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureChallengePreference.md)): Whether the caller prefers a challenge, prefers none, or leaves it to the issuer. Optional. Conditional: When ChallengePreference is not null. (nullable)
  Values:
  - `NoPreference`: Let the issuer decide.
  - `NoChallengeRequested`: Ask the issuer not to challenge.
  - `ChallengeRequested`: Ask the issuer to challenge.
- `challengeWindowSize` ([ThreeDSChallengeWindowSize](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSChallengeWindowSize.md)): The size of the window the caller will present a challenge in. Optional; the issuer is told `500x600` when it is omitted. Conditional: When ChallengeWindowSize is not null. (nullable)
  Values:
  - `Size250X400`: Wire value 01: 250 x 400.
  - `Size390X400`: Wire value 02: 390 x 400.
  - `Size500X600`: Wire value 03: 500 x 600.
  - `Size600X400`: Wire value 04: 600 x 400.
  - `FullScreen`: Wire value 05: full screen.
- `browser` ([ThreeDSecureBrowserDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureBrowserDto.md)) required: The cardholder's browser, as the page that collected the card observed it. Required: the issuer's risk decision is made from it, and a browser authentication that carries none is refused by the vendor. `acceptHeader` and `userAgent` are required; send every other value the page can observe. Conditional: When Browser is not null.
  Fields:
  - `acceptHeader` (string) required: The browser's `Accept` header. (nullable, max length 2048)
  - `userAgent` (string) required: The browser's `User-Agent` header. (nullable, max length 2048)
  - `ipAddress` (string): The cardholder's IP address as the page observed it. (nullable, max length 45)
  - `language` (string): The browser language, for example `en-US`. (nullable, max length 8)
  - `colorDepth` (integer(int32)): The screen color depth in bits. (nullable)
  - `screenHeight` (integer(int32)): The screen height in pixels. (nullable)
  - `screenWidth` (integer(int32)): The screen width in pixels. (nullable)
  - `timeZoneOffsetMinutes` (integer(int32)): The offset between UTC and the browser's local time, in minutes. (nullable)
  - `javaEnabled` (boolean): Whether Java is enabled in the browser. (nullable)
  - `javaScriptEnabled` (boolean): Whether JavaScript is enabled in the browser. (nullable)

_Example: Authenticate a card_

The fields an issuer needs: the card, the amount the transaction will charge, where the issuer returns the cardholder after a challenge, and the cardholder's browser as your page observed it. Replace merchantId with your merchant's id, or omit it for a key bound to one merchant.

```json
{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe"
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "browser": {
    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
}
```

_Example: Authenticate with cardholder details and a challenge preference_

The same authentication with the cardholder's billing address and contact details, which improve the issuer's risk decision, a request that the issuer challenge the cardholder, and the window size your page will present the challenge in.

```json
{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe",
    "email": "john.doe@example.com",
    "phone": "5555550123",
    "billingAddress": {
      "address1": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701",
      "country": "US"
    }
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "challengePreference": "ChallengeRequested",
  "challengeWindowSize": "Size500X600",
  "browser": {
    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
}
```

## Responses

### 200

OK

**Content type:** `application/json`

Schema: [`ThreeDSecureAuthenticateResultDto`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureAuthenticateResultDto.md)

Properties:
- `threeDSServerTransactionId` (string): The 3DS Server transaction id. Submit it as `threeDSecure.threeDSServerTransactionId` on the transaction create request once the authentication is decided. (nullable)
- `messageVersion` (string): The EMVCo message version the authentication ran under, for example `2.2.0`. (nullable)
- `transactionStatus` ([ThreeDSTransactionStatus](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSTransactionStatus.md)): The transaction status the issuer reported.
  Values:
  - `Unknown`: No status was reported, or the value could not be mapped. Treated as "no authentication happened": never liability-shifting.
  - `Authenticated`: Wire value Y: authentication or account verification succeeded.
  - `NotAuthenticated`: Wire value N: not authenticated, or the transaction was denied.
  - `Unavailable`: Wire value U: authentication could not be performed (technical or other problem).
  - `AttemptsProcessed`: Wire value A: an authentication attempt was performed and proof is supplied, but the cardholder was not actually authenticated (the "attempts" / stand-in path).
  - `ChallengeRequired`: Wire value C: a cardholder challenge is required to complete authentication.
  - `DecoupledChallengeRequired`: Wire value D: a decoupled cardholder challenge is required (3DS 2.2 and later).
  - `Rejected`: Wire value R: authentication was rejected by the issuer.
  - `InformationalOnly`: Wire value I: informational only. The 3DS requestor asked for information and no authentication was performed.
- `authenticated` (boolean): Whether the authentication is decided in the cardholder's favor. `false` while a challenge is pending, and for every status other than authenticated or attempts processed.
- `liabilityShifted` (boolean): Whether the issuer shifted liability for the authentication as it stands.
- `eci` (string): The electronic commerce indicator the issuer reported, when the authentication is decided. (nullable)
- `dsTransactionId` (string): The directory server transaction id, when the issuer reported one. (nullable)
- `transactionStatusReason` (string): The issuer's reason for the status, when it gave one. (nullable)
- `challenge` ([ThreeDSecureChallengeDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSecureChallengeDto.md)): The challenge to present to the cardholder, when the issuer asked for one. Absent when the authentication is decided without a challenge.
  Fields:
  - `acsUrl` (string): The access control server URL the challenge form posts to. (nullable)
  - `encodedChallengeRequest` (string): The encoded challenge request to post as the `creq` field. (nullable)
  - `sessionData` (string): The session data to post as `threeDSSessionData`, when the vendor supplies one. (nullable)
  - `challengeWindowSize` ([ThreeDSChallengeWindowSize](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ThreeDSChallengeWindowSize.md)): The window size the challenge request declared.
    Values:
    - `Size250X400`: Wire value 01: 250 x 400.
    - `Size390X400`: Wire value 02: 390 x 400.
    - `Size500X600`: Wire value 03: 500 x 600.
    - `Size600X400`: Wire value 04: 600 x 400.
    - `FullScreen`: Wire value 05: full screen.
  - `acsTransactionId` (string): The access control server transaction id, for the caller's own correlation. (nullable)

### 429

The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause.

**Content type:** `application/problem+json`

Schema: [`RateLimitProblemDetails`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RateLimitProblemDetails.md)

Properties:
- `type` (string) required: The problem type identifier. Always the same value: the failure is the status code itself, so there is no sub-type for a caller to branch on. (nullable)
- `title` (string) required: A short, human-readable summary of the problem type. (nullable)
- `status` (integer(int32)) required: The HTTP status code, repeated in the body as the problem-details format defines.
- `detail` (string) required: A human-readable explanation of this occurrence of the problem. (nullable)
- `retryAfterSeconds` (integer(int32)) required: How long to wait before retrying, in whole seconds, carrying the same figure as the `Retry-After` header. Always at least one: a value of zero would invite an immediate retry that is certain to be rejected again.

**Content type:** `application/json`

Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md)

Properties:
- `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md))

### 400

Bad request. The request was malformed or failed validation. When validation rejected it, `error.validationErrors` names each member at fault and why.

**Content type:** `application/json`

Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md)

Properties:
- `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md))

_Example: Request failed validation_

One or more fields were rejected before any rule ran. error.code is null on the envelope and the causes are in validationErrors, one entry per failure. An entry carries code when the validator declared a publishable one, and memberPaths when the full path says more than members does (an element inside a collection, for example). Both keys are omitted when they would add nothing.

```json
{
  "error": {
    "code": null,
    "message": "Your request is not valid!",
    "details": "The following errors were detected during validation.",
    "data": {
      "correlationId": "0123456789abcdef0123456789abcdef"
    },
    "validationErrors": [
      {
        "message": "'Amount' must be greater than 0.",
        "members": [
          "amount"
        ]
      },
      {
        "message": "The card has expired.",
        "members": [
          "expirationDate"
        ],
        "code": "CardData:CardExpired"
      },
      {
        "message": "'Value' must not be empty.",
        "members": [
          "value"
        ],
        "memberPaths": [
          "customFields[2].value"
        ]
      }
    ]
  }
}
```

### 401

Unauthorized. The request carried no API key or signed-in session, or the key it carried is invalid, revoked or expired.

**Content type:** `application/json`

Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md)

Properties:
- `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md))

### 403

Forbidden. The API key lacks the scope this operation needs, the signed-in user lacks the permission, or a business rule refused the request. The error code in the body names the reason.

**Content type:** `application/json`

Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md)

Properties:
- `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md))

### 404

Not found. The resource the request names does not exist or is not visible to the caller: a resource that belongs to a merchant or tenant outside the caller's scope is reported as not found.

**Content type:** `application/json`

Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md)

Properties:
- `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md))

_Example: Resource not found_

The id in the path names no record the caller can see. Most resources answer with a null error.code and a message naming the resource type and the id; a resource that publishes a not-found code in the catalog above carries it in error.code instead, so check for one before matching on the message.

```json
{
  "error": {
    "code": null,
    "message": "There is no entity Transaction with id = 7d1f3a52-0c4e-4b8a-9e21-5a6b7c8d9e00!",
    "details": null,
    "data": {
      "correlationId": "0123456789abcdef0123456789abcdef"
    },
    "validationErrors": null
  }
}
```

### 500

Internal server error. The platform failed unexpectedly while handling the request. If it keeps failing, contact support and quote the correlation id, which the response carries in the `X-Correlation-Id` header and as `error.data.correlationId`.

**Content type:** `application/json`

Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md)

Properties:
- `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md))

### 501

Not implemented. The operation is declared but has no implementation on this deployment, so no request to it can succeed. Retrying does not help.

**Content type:** `application/json`

Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md)

Properties:
- `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md))

### default

The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The [error reference](https://devportal.signapay-sbx.winkpg.io/docs/errors.md) lists the values `error.code` can take.

**Content type:** `application/json`

Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md)

Properties:
- `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md))

_Example: Business rule refused the request_

The request was understood and rejected by a platform rule. This is the shape that carries a code from the catalog above, so branch on error.code rather than on the message text. The HTTP status is the one listed against the code.

```json
{
  "error": {
    "code": "Transactions:OperationNotAllowed",
    "message": "The operation 'Void' is not allowed on a Sale transaction with result 'Approved' and settlement state 'Settled'.",
    "details": null,
    "data": {
      "correlationId": "0123456789abcdef0123456789abcdef"
    },
    "validationErrors": null
  }
}
```

### Errors

These statuses answer with the error envelope outlined below.

- `400`: Bad request. The request was malformed or failed validation. When validation rejected it, `error.validationErrors` names each member at fault and why.
- `401`: Unauthorized. The request carried no API key or signed-in session, or the key it carried is invalid, revoked or expired.
- `403`: Forbidden. The API key lacks the scope this operation needs, the signed-in user lacks the permission, or a business rule refused the request. The error code in the body names the reason.
- `404`: Not found. The resource the request names does not exist or is not visible to the caller: a resource that belongs to a merchant or tenant outside the caller's scope is reported as not found.
- `500`: Internal server error. The platform failed unexpectedly while handling the request. If it keeps failing, contact support and quote the correlation id, which the response carries in the `X-Correlation-Id` header and as `error.data.correlationId`.
- `501`: Not implemented. The operation is declared but has no implementation on this deployment, so no request to it can succeed. Retrying does not help.
- `default`: The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The [error reference](https://devportal.signapay-sbx.winkpg.io/docs/errors.md) lists the values `error.code` can take.

**Content type:** `application/json`

Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md)

Properties:
- `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md))
  Fields:
  - `code` (string): (nullable)
  - `message` (string): (nullable)
  - `details` (string): (nullable)
  - `data` (object): (nullable)
  - `validationErrors` (array<[RemoteServiceValidationErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceValidationErrorInfo.md)>): (nullable)

_Example: Request failed validation_

One or more fields were rejected before any rule ran. error.code is null on the envelope and the causes are in validationErrors, one entry per failure. An entry carries code when the validator declared a publishable one, and memberPaths when the full path says more than members does (an element inside a collection, for example). Both keys are omitted when they would add nothing.

```json
{
  "error": {
    "code": null,
    "message": "Your request is not valid!",
    "details": "The following errors were detected during validation.",
    "data": {
      "correlationId": "0123456789abcdef0123456789abcdef"
    },
    "validationErrors": [
      {
        "message": "'Amount' must be greater than 0.",
        "members": [
          "amount"
        ]
      },
      {
        "message": "The card has expired.",
        "members": [
          "expirationDate"
        ],
        "code": "CardData:CardExpired"
      },
      {
        "message": "'Value' must not be empty.",
        "members": [
          "value"
        ],
        "memberPaths": [
          "customFields[2].value"
        ]
      }
    ]
  }
}
```

## Authentication

- `ApiKey`

## Example request

Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.

The request body is a ThreeDSecureAuthenticateInputDto. See the Request body section below for its fields.

These blocks send the Authenticate a card example. The other examples follow under Other request examples.

The fields an issuer needs: the card, the amount the transaction will charge, where the issuer returns the cardholder after a challenge, and the cardholder's browser as your page observed it. Replace merchantId with your merchant's id, or omit it for a key bound to one merchant.

### cURL

```bash
curl -X POST "{{BASE_URL}}/api/transactions/three-d-secure/authenticate" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe"
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "browser": {
    "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
}'
```

### PowerShell

```powershell
$headers = @{
    'api-key' = '{{API_KEY}}'
}

$body = @'
{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe"
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "browser": {
    "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/transactions/three-d-secure/authenticate' `
    -Headers $headers -ContentType 'application/json' -Body $body
```

### TypeScript (SDK)

```bash
npm install @winkpg/winkpg-api
```

```typescript
import { Configuration, TransactionsApi } from '@winkpg/winkpg-api';

const api = new TransactionsApi(new Configuration({
  basePath: '{{BASE_URL}}',
  apiKey: '{{API_KEY}}',
}));

const { data } = await api.threeDSecureAuthenticate({
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe"
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "browser": {
    "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
});
```

### TypeScript (raw HTTP)

```typescript
const response = await fetch('{{BASE_URL}}/api/transactions/three-d-secure/authenticate', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "merchantId": "00000000-0000-0000-0000-000000000001",
    "cardData": {
      "cardNumber": "4111111111111111",
      "expirationMonth": 12,
      "expirationYear": 2030,
      "nameOnCard": "John Doe"
    },
    "amount": 49.99,
    "currencyCode": "USD",
    "challengeReturnUrl": "https://checkout.example.com/3ds/return",
    "browser": {
      "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
      "ipAddress": "203.0.113.9",
      "language": "en-US",
      "colorDepth": 24,
      "screenHeight": 900,
      "screenWidth": 1440,
      "timeZoneOffsetMinutes": 300,
      "javaEnabled": false,
      "javaScriptEnabled": true
    }
  }),
});

const data = await response.json();
```

### C# (SDK)

```bash
dotnet add package WinkPg.Api.Client
```

```csharp
using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;
using System.Text.Json;

var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");

var api = new TransactionsApi(config);
var body = JsonSerializer.Deserialize<ThreeDSecureAuthenticateInputDto>("""
    {
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "nameOnCard": "John Doe"
      },
      "amount": 49.99,
      "currencyCode": "USD",
      "challengeReturnUrl": "https://checkout.example.com/3ds/return",
      "browser": {
        "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
        "ipAddress": "203.0.113.9",
        "language": "en-US",
        "colorDepth": 24,
        "screenHeight": 900,
        "screenWidth": 1440,
        "timeZoneOffsetMinutes": 300,
        "javaEnabled": false,
        "javaScriptEnabled": true
      }
    }
    """);

var result = await api.ThreeDSecureAuthenticateAsync(body);
```

### C# (raw HTTP)

```csharp
using System.Text;

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };

var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/transactions/three-d-secure/authenticate");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "nameOnCard": "John Doe"
      },
      "amount": 49.99,
      "currencyCode": "USD",
      "challengeReturnUrl": "https://checkout.example.com/3ds/return",
      "browser": {
        "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
        "ipAddress": "203.0.113.9",
        "language": "en-US",
        "colorDepth": 24,
        "screenHeight": 900,
        "screenWidth": 1440,
        "timeZoneOffsetMinutes": 300,
        "javaEnabled": false,
        "javaScriptEnabled": true
      }
    }
    """, Encoding.UTF8, "application/json");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();
```

### Python (SDK)

```bash
pip install winkpg-api
```

```python
import winkpg_api

configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"

with winkpg_api.ApiClient(configuration) as client:
    api = winkpg_api.TransactionsApi(client)
    body = winkpg_api.ThreeDSecureAuthenticateInputDto.from_dict({
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "nameOnCard": "John Doe"
      },
      "amount": 49.99,
      "currencyCode": "USD",
      "challengeReturnUrl": "https://checkout.example.com/3ds/return",
      "browser": {
        "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
        "ipAddress": "203.0.113.9",
        "language": "en-US",
        "colorDepth": 24,
        "screenHeight": 900,
        "screenWidth": 1440,
        "timeZoneOffsetMinutes": 300,
        "javaEnabled": False,
        "javaScriptEnabled": True
      }
    })
    result = api.three_d_secure_authenticate(body)
```

### Python (raw HTTP)

```bash
pip install requests
```

```python
import requests

headers = {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
}

body = {
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe"
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "browser": {
    "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": False,
    "javaScriptEnabled": True
  }
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/transactions/three-d-secure/authenticate",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()
```

## Other request examples

Each example below is one request, shown in every language with the same placeholders.

### Authenticate with cardholder details and a challenge preference

The same authentication with the cardholder's billing address and contact details, which improve the issuer's risk decision, a request that the issuer challenge the cardholder, and the window size your page will present the challenge in.

#### cURL

```bash
curl -X POST "{{BASE_URL}}/api/transactions/three-d-secure/authenticate" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe",
    "email": "john.doe@example.com",
    "phone": "5555550123",
    "billingAddress": {
      "address1": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701",
      "country": "US"
    }
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "challengePreference": "ChallengeRequested",
  "challengeWindowSize": "Size500X600",
  "browser": {
    "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
}'
```

#### PowerShell

```powershell
$headers = @{
    'api-key' = '{{API_KEY}}'
}

$body = @'
{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe",
    "email": "john.doe@example.com",
    "phone": "5555550123",
    "billingAddress": {
      "address1": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701",
      "country": "US"
    }
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "challengePreference": "ChallengeRequested",
  "challengeWindowSize": "Size500X600",
  "browser": {
    "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/transactions/three-d-secure/authenticate' `
    -Headers $headers -ContentType 'application/json' -Body $body
```

#### TypeScript (SDK)

```bash
npm install @winkpg/winkpg-api
```

```typescript
import { Configuration, TransactionsApi } from '@winkpg/winkpg-api';

const api = new TransactionsApi(new Configuration({
  basePath: '{{BASE_URL}}',
  apiKey: '{{API_KEY}}',
}));

const { data } = await api.threeDSecureAuthenticate({
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe",
    "email": "john.doe@example.com",
    "phone": "5555550123",
    "billingAddress": {
      "address1": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701",
      "country": "US"
    }
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "challengePreference": "ChallengeRequested",
  "challengeWindowSize": "Size500X600",
  "browser": {
    "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": false,
    "javaScriptEnabled": true
  }
});
```

#### TypeScript (raw HTTP)

```typescript
const response = await fetch('{{BASE_URL}}/api/transactions/three-d-secure/authenticate', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "merchantId": "00000000-0000-0000-0000-000000000001",
    "cardData": {
      "cardNumber": "4111111111111111",
      "expirationMonth": 12,
      "expirationYear": 2030,
      "nameOnCard": "John Doe",
      "email": "john.doe@example.com",
      "phone": "5555550123",
      "billingAddress": {
        "address1": "123 Main St",
        "city": "Springfield",
        "state": "IL",
        "zip": "62701",
        "country": "US"
      }
    },
    "amount": 49.99,
    "currencyCode": "USD",
    "challengeReturnUrl": "https://checkout.example.com/3ds/return",
    "challengePreference": "ChallengeRequested",
    "challengeWindowSize": "Size500X600",
    "browser": {
      "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
      "ipAddress": "203.0.113.9",
      "language": "en-US",
      "colorDepth": 24,
      "screenHeight": 900,
      "screenWidth": 1440,
      "timeZoneOffsetMinutes": 300,
      "javaEnabled": false,
      "javaScriptEnabled": true
    }
  }),
});

const data = await response.json();
```

#### C# (SDK)

```bash
dotnet add package WinkPg.Api.Client
```

```csharp
using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;
using System.Text.Json;

var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");

var api = new TransactionsApi(config);
var body = JsonSerializer.Deserialize<ThreeDSecureAuthenticateInputDto>("""
    {
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "nameOnCard": "John Doe",
        "email": "john.doe@example.com",
        "phone": "5555550123",
        "billingAddress": {
          "address1": "123 Main St",
          "city": "Springfield",
          "state": "IL",
          "zip": "62701",
          "country": "US"
        }
      },
      "amount": 49.99,
      "currencyCode": "USD",
      "challengeReturnUrl": "https://checkout.example.com/3ds/return",
      "challengePreference": "ChallengeRequested",
      "challengeWindowSize": "Size500X600",
      "browser": {
        "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
        "ipAddress": "203.0.113.9",
        "language": "en-US",
        "colorDepth": 24,
        "screenHeight": 900,
        "screenWidth": 1440,
        "timeZoneOffsetMinutes": 300,
        "javaEnabled": false,
        "javaScriptEnabled": true
      }
    }
    """);

var result = await api.ThreeDSecureAuthenticateAsync(body);
```

#### C# (raw HTTP)

```csharp
using System.Text;

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };

var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/transactions/three-d-secure/authenticate");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "nameOnCard": "John Doe",
        "email": "john.doe@example.com",
        "phone": "5555550123",
        "billingAddress": {
          "address1": "123 Main St",
          "city": "Springfield",
          "state": "IL",
          "zip": "62701",
          "country": "US"
        }
      },
      "amount": 49.99,
      "currencyCode": "USD",
      "challengeReturnUrl": "https://checkout.example.com/3ds/return",
      "challengePreference": "ChallengeRequested",
      "challengeWindowSize": "Size500X600",
      "browser": {
        "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
        "ipAddress": "203.0.113.9",
        "language": "en-US",
        "colorDepth": 24,
        "screenHeight": 900,
        "screenWidth": 1440,
        "timeZoneOffsetMinutes": 300,
        "javaEnabled": false,
        "javaScriptEnabled": true
      }
    }
    """, Encoding.UTF8, "application/json");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();
```

#### Python (SDK)

```bash
pip install winkpg-api
```

```python
import winkpg_api

configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"

with winkpg_api.ApiClient(configuration) as client:
    api = winkpg_api.TransactionsApi(client)
    body = winkpg_api.ThreeDSecureAuthenticateInputDto.from_dict({
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "nameOnCard": "John Doe",
        "email": "john.doe@example.com",
        "phone": "5555550123",
        "billingAddress": {
          "address1": "123 Main St",
          "city": "Springfield",
          "state": "IL",
          "zip": "62701",
          "country": "US"
        }
      },
      "amount": 49.99,
      "currencyCode": "USD",
      "challengeReturnUrl": "https://checkout.example.com/3ds/return",
      "challengePreference": "ChallengeRequested",
      "challengeWindowSize": "Size500X600",
      "browser": {
        "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
        "ipAddress": "203.0.113.9",
        "language": "en-US",
        "colorDepth": 24,
        "screenHeight": 900,
        "screenWidth": 1440,
        "timeZoneOffsetMinutes": 300,
        "javaEnabled": False,
        "javaScriptEnabled": True
      }
    })
    result = api.three_d_secure_authenticate(body)
```

#### Python (raw HTTP)

```bash
pip install requests
```

```python
import requests

headers = {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
}

body = {
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "nameOnCard": "John Doe",
    "email": "john.doe@example.com",
    "phone": "5555550123",
    "billingAddress": {
      "address1": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701",
      "country": "US"
    }
  },
  "amount": 49.99,
  "currencyCode": "USD",
  "challengeReturnUrl": "https://checkout.example.com/3ds/return",
  "challengePreference": "ChallengeRequested",
  "challengeWindowSize": "Size500X600",
  "browser": {
    "acceptHeader": "text/html,application/xhtml\u002Bxml,application/xml;q=0.9,*/*;q=0.8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
    "ipAddress": "203.0.113.9",
    "language": "en-US",
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffsetMinutes": 300,
    "javaEnabled": False,
    "javaScriptEnabled": True
  }
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/transactions/three-d-secure/authenticate",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()
```

## See also

- [All documentation](https://devportal.signapay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.