# 3D Secure: External Provider

Pass authentication values from a third-party 3D Secure vendor through to the gateway on your authorization call.

Source: https://developer.inoviopay.com/api/3ds-external.html  
Markdown: https://developer.inoviopay.com/api/3ds-external.md

If you perform 3D Secure authentication through a third-party vendor before the transaction, you must pass the resulting authentication values to the gateway.

| Parameter | Description |
|---|---|
| `P3DS_CAVV` (required) | Cardholder Authentication Verification Value. |
| `P3DS_ECI` (required) | Electronic Commerce Indicator. |
| `P3DS_XID` (required) | Transaction ID. |
| `P3DS_VERSION` (required) | Reports on 3DS Version used to process Transaction (Required for Mastercard Identity Check transactions in Authorization on 3DS 2). |
| `P3DS_TRANSID` (required) | Unique transaction identifier assigned by the Directory Server (DS) - (Required for Mastercard Identity Check transactions in Authorization IF `P3DS_VERSION` is 3DS 2). |
| `P3DS_SCREEN_HEIGHT` (optional) | Total height of the cardholder's screen in pixels. |
| `P3DS_SCREEN_WIDTH` (optional) | Total width of the cardholder's screen in pixels. |
| `P3DS_JAVA_ENABLED` (optional) | A Boolean value (TRUE/FALSE) that represents the ability of the cardholder browser to execute Java. |
| `P3DS_JAVASCRIPT_ENABLED` (optional) | A Boolean value (TRUE/FALSE) that represents the ability of the cardholder browser to execute JavaScript. |
| `P3DS_BROWSER_HEADER` (optional) | The exact content of the HTTP accept headers sent from the cardholder's browser. Example: `text/html,application/xhtml+xml,application/xml;q=0.9,*/*; q=0.8` |
| `P3DS_BROWSER_LANGUAGE` (optional) | Value represents the browser language as defined in IETF BCP47. |
| `P3DS_BROWSER_COLOR_DEPTH` (optional) | Value represents the bit depth of the color palette for displaying images, in bits per pixel. Possible Values: 1, 4, 8, 15, 16, 24, 32, 48. |
| `P3DS_BROWSER_TIME_ZONE` (optional) | Time difference between UTC time and the cardholder browser local time, in minutes. Note: Regardless of direction value should be positive. |
| `P3DS_CHALLENGE_WINDOW` (optional) | An override field that a merchant can pass in to set the challenge window size to display to the end cardholder. Possible values: 01 - 250x400, 02 - 390x400, 03 - 500x600, 04 - 600x400, 05 - Full page. |
| `USER_AGENT_XTL` (optional) | Software agent responsible for retrieving and facilitating end-user interaction with Web content. |
| `XTL_IP` (optional) | Cardholder's IP Address. |

These parameters are add-ons to a standard authorization call (for example `CCAUTHCAP` or `CCAUTHORIZE`), not a `REQUEST_ACTION` of their own. Attach them to the same request as your regular payment fields.

> **Only the PHP SDK implements this path**
> `ThreeDSResult`, the model for an externally-obtained 3DS authentication attached to a normal one-leg `sale()`/`authorize()`, exists only in the PHP SDK (`Inovio\Gateway\Model\ThreeDSResult`). Node, Python and Java carry `BrowserData` on the request and read the gateway's own challenge outcome from `nextAction`, but none of the three has an equivalent for attaching CAVV/ECI/XID values from a third-party 3DS provider. Use the cURL example directly in those languages, or see [the SDKs](https://developer.inoviopay.com/sdks/index.md).

**cURL**

```bash
curl -X POST "https://api.inoviopay.com/payment/pmt_service.cfm" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "request_action=CCAUTHCAP&req_username=api_user&req_password=P%40ssw0rd%21&site_id=12345&request_api_version=4.14&request_response_format=JSON&pmt_numb=4111111111111111&pmt_expiry=122026&pmt_key=123&request_currency=USD&li_value_1=49.99&xtl_order_id=INV-999&p3ds_cavv=[CAVV_FROM_YOUR_3DS_PROVIDER]&p3ds_eci=05&p3ds_xid=[XID_FROM_YOUR_3DS_PROVIDER]&p3ds_version=2.2.0&p3ds_transid=[DS_TRANSID_FROM_YOUR_3DS_PROVIDER]"
```

**PHP**

```php
use Inovio\Gateway\{Credentials, InovioClient};
use Inovio\Gateway\Model\{LineItem, Money, PaymentMethods, ThreeDSResult};
use Inovio\Gateway\Request\TransactionRequest;

$client = new InovioClient(new Credentials('api_user', 'P@ssw0rd!', '12345'), 'SANDBOX');

$req = (new TransactionRequest(
    PaymentMethods::card('4111111111111111', '122026', '123'),
    [new LineItem('SKU-992', 1, Money::of('49.99', 'USD'))]
))->withIdempotency('INV-999');

// One leg, no redirect — the authentication already happened with your provider.
$req->threeDSResult = new ThreeDSResult(
    cavv: '[CAVV_FROM_YOUR_3DS_PROVIDER]',
    eci: '05',
    transId: '[DS_TRANSID_FROM_YOUR_3DS_PROVIDER]',
    version: '2.2.0',
    xid: '[XID_FROM_YOUR_3DS_PROVIDER]'
);

$result = $client->sale($req);

match ($result->status) {
    'APPROVED' => /* $result->threeDS->eci — 05/06 means full authentication (liability shift) */,
    'DECLINED' => /* $result->outcome->service */,
    default => /* PENDING | RUNNING | FAILED */,
};
```

**Response**

```json
{
  "REQUEST_ACTION": "CCAUTHCAP",
  "REQ_ID": "68192033",
  "TRANS_STATUS_NAME": "APPROVED",
  "TRANS_VALUE": 49.99,
  "CURR_CODE_ALPHA": "USD",
  "TRANS_VALUE_SETTLED": 49.99,
  "CURR_CODE_ALPHA_SETTLED": "USD",
  "TRANS_EXCH_RATE": "",
  "TRANS_ID": 8839201112,
  "CUST_ID": 9928102,
  "XTL_CUST_ID": "cUsT992xP",
  "PO_ID": 77281920,
  "XTL_ORDER_ID": "INV-999",
  "BATCH_ID": 882910,
  "PROC_NAME": "Inovio Primary",
  "MERCH_ACCT_ID": 110203,
  "CARD_BRAND_NAME": "Mastercard",
  "CARD_TYPE": "MASTERCARD BLACK CARD",
  "CARD_CLASS": "Consumer Credit",
  "CARD_PREPAID": 0,
  "CARD_BANK": "CREDOMATIC INTERNATIONAL",
  "CARD_COUNTRY": "CRI",
  "CARD_DETAIL": "Credit",
  "CARD_BALANCE": "",
  "PMT_L4": "3535",
  "PMT_ID": 8829102,
  "PMT_ID_XTL": "",
  "PMT_AAU_UPDATE_DT": "",
  "PMT_AAU_UPDATE_DESC": "",
  "PROC_UDF01": "",
  "ANI_RESP_DECISION": "",
  "PROC_UDF02": "",
  "PROC_AUTH_RESPONSE": "AUTH99",
  "PROC_RETRIEVAL_NUM": "1029384A-B8C7-D6E5-F4G3-H2I1J0K9L8M7",
  "PROC_REFERENCE_NUM": "REF10293847",
  "PROC_REDIRECT_URL": "",
  "AVS_RESPONSE": "M",
  "CVV_RESPONSE": "M",
  "CARD_BRAND_TRANSID": "",
  "REQUEST_API_VERSION": "4.14",
  "P3DS_VENDOR": "[YOUR_3DS_PROVIDER]",
  "P3DS_RESPONSE": "Y",
  "PO_LI_ID_1": "8829103",
  "PO_LI_COUNT_1": 1,
  "PO_LI_AMOUNT_1": "49.99",
  "PO_LI_PROD_ID_1": "SKU-992",
  "MBSHP_ID_1": "88291",
  "TRANS_NTOKEN_USED": 1
}
```