3D Secure Authentication

This page is part of the REST API Guides. For 3D Secure at capture time, handled automatically, see Payments Library 3D Secure.

Prerequisites: API key, Payment Gateway Account with a 3DS-capable gateway, and a 3DS authentication provider. 3D Secure (3DS) is an authentication protocol that adds an extra layer of security for online card transactions. It helps reduce fraud and liability by verifying the cardholder’s identity before completing the payment.

On this path Orchestra does not perform the authentication. You authenticate the cardholder with your own 3DS provider and pass the results to Orchestra, which forwards them to the PSP. No 3DS configuration is required on your Orchestra account.If you want Orchestra to run the 3DS challenge for you, use the Payments Library or the eWallet operations endpoints instead. That path does require 3DS merchant details on the CardPay eWallet account.

Passing 3DS Authentication Data to PSPs

Many of Orchestra’s PSP integrations support receiving 3DS authentication data. If you have already performed 3DS authentication for a card (using your own 3DS provider or a third-party service), you can pass those authentication results to Orchestra when making a charge request.

For a complete list of PSP integrations that support 3DS data, see 3D Secure Integrations.

3DS Authentication Fields

When you have 3DS authentication results, include them in the threeDSAuthentication object within the card details:

Field	Description
`authenticationValue`	The cryptographic authentication value (CAVV for Visa, AAV for Mastercard)
`eci`	Electronic Commerce Indicator - indicates the outcome of the 3DS authentication
`xid`	Transaction identifier from the 3DS authentication
`version`	The 3DS protocol version used (e.g., “2.1.0”, “2.2.0”)
`merchantName`	The merchant name used during 3DS authentication
`sli`	Security Level Indicator

Example: Charge with 3DS Data

The standard integration passes 3DS authentication data alongside a token captured by the Payments Library. Reference it in the cardNumber field with an @ prefix; cvv is optional and can be left out for a tokenized card.

const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/charge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    paymentGatewayAccountName: 'yourGatewayAccount',
    amount: 25.00,
    currency: 'USD',
    myRef: 'PaymentX112358',
    card: {
      cardType: 'Visa',
      cardHolderName: 'Jane Smith',
      cardNumber: '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
      expirationMonth: 12,
      expirationYear: 2027,
      threeDSAuthentication: {
        authenticationValue: 'AJkBABkhYQAAAABVYCFhAAAAAAA=',
        eci: '05',
        xid: 'MDAwMDAwMDAwMDAwMDAwMDAwMDE=',
        version: '2.2.0',
        merchantName: 'Your Merchant Name',
        sli: '02'
      }
    }
  })
});

const result = await response.json();

curl -X POST https://api.orchestrasolutions.com/PaymentGateway/charge \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "paymentGatewayAccountName": "yourGatewayAccount",
    "amount": 25.00,
    "currency": "USD",
    "myRef": "PaymentX112358",
    "card": {
      "cardType": "Visa",
      "cardHolderName": "Jane Smith",
      "cardNumber": "@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO",
      "expirationMonth": 12,
      "expirationYear": 2027,
      "threeDSAuthentication": {
        "authenticationValue": "AJkBABkhYQAAAABVYCFhAAAAAAA=",
        "eci": "05",
        "xid": "MDAwMDAwMDAwMDAwMDAwMDAwMDE=",
        "version": "2.2.0",
        "merchantName": "Your Merchant Name",
        "sli": "02"
      }
    }
  }'

import requests

response = requests.post(
    'https://api.orchestrasolutions.com/PaymentGateway/charge',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'paymentGatewayAccountName': 'yourGatewayAccount',
        'amount': 25.00,
        'currency': 'USD',
        'myRef': 'PaymentX112358',
        'card': {
            'cardType': 'Visa',
            'cardHolderName': 'Jane Smith',
            'cardNumber': '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
            'expirationMonth': 12,
            'expirationYear': 2027,
            'threeDSAuthentication': {
                'authenticationValue': 'AJkBABkhYQAAAABVYCFhAAAAAAA=',
                'eci': '05',
                'xid': 'MDAwMDAwMDAwMDAwMDAwMDAwMDE=',
                'version': '2.2.0',
                'merchantName': 'Your Merchant Name',
                'sli': '02'
            }
        }
    }
)

If your backend already lawfully holds card data and needs to send it directly, see Sending Raw Card Details (Non-Standard) below.

Sending Raw Card Details (Non-Standard)

This example shows raw card details for completeness. Sending raw card data means it passes through your systems and puts you in PCI DSS scope. The standard integration captures the card with the Payments Library and references it here as a token (an @TOKEN value in the cardNumber field); see Example: Charge with 3DS Data above.

const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/charge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    paymentGatewayAccountName: 'yourGatewayAccount',
    amount: 25.00,
    currency: 'USD',
    myRef: 'PaymentX112358',
    card: {
      cardType: 'Visa',
      cardHolderName: 'Jane Smith',
      cardNumber: '4111111111111111',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123',
      threeDSAuthentication: {
        authenticationValue: 'AJkBABkhYQAAAABVYCFhAAAAAAA=',
        eci: '05',
        xid: 'MDAwMDAwMDAwMDAwMDAwMDAwMDE=',
        version: '2.2.0',
        merchantName: 'Your Merchant Name',
        sli: '02'
      }
    }
  })
});

const result = await response.json();

curl -X POST https://api.orchestrasolutions.com/PaymentGateway/charge \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "paymentGatewayAccountName": "yourGatewayAccount",
    "amount": 25.00,
    "currency": "USD",
    "myRef": "PaymentX112358",
    "card": {
      "cardType": "Visa",
      "cardHolderName": "Jane Smith",
      "cardNumber": "4111111111111111",
      "expirationMonth": 12,
      "expirationYear": 2027,
      "cvv": "123",
      "threeDSAuthentication": {
        "authenticationValue": "AJkBABkhYQAAAABVYCFhAAAAAAA=",
        "eci": "05",
        "xid": "MDAwMDAwMDAwMDAwMDAwMDAwMDE=",
        "version": "2.2.0",
        "merchantName": "Your Merchant Name",
        "sli": "02"
      }
    }
  }'

import requests

response = requests.post(
    'https://api.orchestrasolutions.com/PaymentGateway/charge',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'paymentGatewayAccountName': 'yourGatewayAccount',
        'amount': 25.00,
        'currency': 'USD',
        'myRef': 'PaymentX112358',
        'card': {
            'cardType': 'Visa',
            'cardHolderName': 'Jane Smith',
            'cardNumber': '4111111111111111',
            'expirationMonth': 12,
            'expirationYear': 2027,
            'cvv': '123',
            'threeDSAuthentication': {
                'authenticationValue': 'AJkBABkhYQAAAABVYCFhAAAAAAA=',
                'eci': '05',
                'xid': 'MDAwMDAwMDAwMDAwMDAwMDAwMDE=',
                'version': '2.2.0',
                'merchantName': 'Your Merchant Name',
                'sli': '02'
            }
        }
    }
)

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

Passing 3DS Authentication Data to PSPs

3DS Authentication Fields

Example: Charge with 3DS Data

Sending Raw Card Details (Non-Standard)

What’s Next

Charge Payments

Authorize & Capture

​Passing 3DS Authentication Data to PSPs

​3DS Authentication Fields

​Example: Charge with 3DS Data

​Sending Raw Card Details (Non-Standard)

​What’s Next

Charge Payments

Authorize & Capture

Passing 3DS Authentication Data to PSPs

3DS Authentication Fields

Example: Charge with 3DS Data

Sending Raw Card Details (Non-Standard)

What’s Next