WinkPG Docs
View as Markdown

llms.txt

The API reference isn't available right now

This instance couldn't load its API specification. The reference returns as soon as the specification is readable again.

Back to the API reference

No such operation

This instance documents no operation under that identifier. It may have been renamed, or it may belong to a feature this installation hasn't enabled.

Back to the API reference

This reference may be out of date

This instance couldn't reach its API specification on the last attempt, so this page shows the copy fetched before that. Anything added or changed since then is missing here, and the reference updates itself as soon as the specification is readable again. Last fetched 2026-11-12 05:58 UTC.

API reference Transactions

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

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

Requires: Transactions.Payments.Create, merchant scope.

Requires API key scope: transactions:write (Take payments)

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.

Signed in, you can send this request to your own sandbox merchant from the console and read the answer. Sign in to try it.

Example request

Each example below is one request, shown in every language. Choose an example and a language, then 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.

Code sample language
Request example

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

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

$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

npm install @winkpg/winkpg-api

TypeScript (SDK)

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)

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();

dotnet add package WinkPg.Api.Client

C# (SDK)

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)

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();

pip install winkpg-api

Python (SDK)

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)

pip install requests

Python (raw HTTP)

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()

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

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

$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

npm install @winkpg/winkpg-api

TypeScript (SDK)

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)

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();

dotnet add package WinkPg.Api.Client

C# (SDK)

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)

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();

pip install winkpg-api

Python (SDK)

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)

pip install requests

Python (raw HTTP)

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()

Parameters

Name In Type Description
suppressNulls required query boolean If true, omit properties with null values.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Request body

application/json , required

Field Type Description
merchantId required 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
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
cardData required ThreeDSecureCardDto ThreeDSecureCardDto 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.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of ThreeDSecureCardDto:

Field Type Description
cardNumber required string 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
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
expirationMonth required integer (int32) The expiration month, 1 to 12. Required. nullablemin 1max 12
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
expirationYear required integer (int32) 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). nullablemin 2000max 2099
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
nameOnCard required string The name on the card. Optional. nullablemax length 100
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
email required string The cardholder's email address. Optional. nullablemax length 254
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
phone required string The cardholder's phone number. Optional. nullablemax length 32
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
billingAddress required Address Address The cardholder's billing address. Optional. Conditional: When BillingAddress is not null.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

amount required number (double) 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
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
currencyCode required 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
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
challengeReturnUrl required string 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. nullablemax length 2048
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
challengePreference required ThreeDSecureChallengePreference ThreeDSecureChallengePreference Whether the caller prefers a challenge, prefers none, or leaves it to the issuer. Optional. Conditional: When ChallengePreference is not null. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
NoPreference Let the issuer decide.
NoChallengeRequested Ask the issuer not to challenge.
ChallengeRequested Ask the issuer to challenge.
challengeWindowSize required ThreeDSChallengeWindowSize ThreeDSChallengeWindowSize 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: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
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 required ThreeDSecureBrowserDto ThreeDSecureBrowserDto 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.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of ThreeDSecureBrowserDto:

Field Type Description
acceptHeader required string The browser's `Accept` header. nullablemax length 2048
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
userAgent required string The browser's `User-Agent` header. nullablemax length 2048
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
ipAddress required string The cardholder's IP address as the page observed it. nullablemax length 45
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
language required string The browser language, for example `en-US`. nullablemax length 8
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
colorDepth required integer (int32) The screen color depth in bits. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
screenHeight required integer (int32) The screen height in pixels. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
screenWidth required integer (int32) The screen width in pixels. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
timeZoneOffsetMinutes required integer (int32) The offset between UTC and the browser's local time, in minutes. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
javaEnabled required boolean Whether Java is enabled in the browser. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
javaScriptEnabled required boolean Whether JavaScript is enabled in the browser. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

This request body has no documented fields.

Responses

Response status

OK

Body: ThreeDSecureAuthenticateResultDto ThreeDSecureAuthenticateResultDto Each item has these fields.

Field Type Description
threeDSServerTransactionId required string The 3DS Server transaction id. Submit it as `threeDSecure.threeDSServerTransactionId` on the transaction create request once the authentication is decided. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
messageVersion required string The EMVCo message version the authentication ran under, for example `2.2.0`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
transactionStatus required ThreeDSTransactionStatus ThreeDSTransactionStatus The transaction status the issuer reported.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
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 required 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.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
liabilityShifted required boolean Whether the issuer shifted liability for the authentication as it stands.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
eci required string The electronic commerce indicator the issuer reported, when the authentication is decided. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
dsTransactionId required string The directory server transaction id, when the issuer reported one. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
transactionStatusReason required string The issuer's reason for the status, when it gave one. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
challenge required ThreeDSecureChallengeDto ThreeDSecureChallengeDto The challenge to present to the cardholder, when the issuer asked for one. Absent when the authentication is decided without a challenge.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of ThreeDSecureChallengeDto:

Field Type Description
acsUrl required string The access control server URL the challenge form posts to. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
encodedChallengeRequest required string The encoded challenge request to post as the `creq` field. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
sessionData required string The session data to post as `threeDSSessionData`, when the vendor supplies one. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
challengeWindowSize required ThreeDSChallengeWindowSize ThreeDSChallengeWindowSize The window size the challenge request declared.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
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 required string The access control server transaction id, for the caller's own correlation. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

This response has no documented body fields.

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.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

  1. 400 Bad Request Bad request. The request was malformed or failed validation. When validation rejected it, `error.validationErrors` names each member at fault and why.
  2. 401 Unauthorized Unauthorized. The request carried no API key or signed-in session, or the key it carried is invalid, revoked or expired.
  3. 403 Forbidden 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.
  4. 404 Not Found 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.
  5. 500 Internal Server Error 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`.
  6. 501 Not Implemented Not implemented. The operation is declared but has no implementation on this deployment, so no request to it can succeed. Retrying does not help.
  7. 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 lists the values `error.code` can take.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 lists the values `error.code` can take.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of RemoteServiceErrorInfo:

Field Type Description
code required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
message required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
details required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
data required object nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
validationErrors required array of RemoteServiceValidationErrorInfo array of RemoteServiceValidationErrorInfo nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

This response has no documented body fields.

Errors

A failed request returns the platform error envelope. The error reference lists every value error.code can carry and shows the four response shapes.

Codes declared by Transactions

Authentication

  • ApiKey with scopes

Reconnecting to the server

Could not reconnect

This session has ended

Attempt 1

Your work on this page is still here. Retrying keeps it; reloading starts the page again.

The server no longer holds this page's state, so it has to be loaded again.