> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/merchant-configuration/cybersource-device-fingerprinting.md).

# Cybersource Device Fingerprinting

Plexo configures Cybersource device fingerprinting in the existing fraud-management pipeline for each merchant payment method. The backend owns the pipeline metadata. Do not create, replace, or extend collection URLs in a merchant payment-method request.

## Discover collection targets

For a direct integration, retrieve the merchant's configured payment methods before starting a browser collector:

```
GET /v1/merchants/{merchantId}/payment-methods
```

For hosted checkout and tokenization, read the same data from the session response:

```
POST /v1/sessions
→ SessionDto.merchant.paymentMethods[].settings.fraudManagement.pipeline[]
```

Read `MerchantPaymentMethodDto.settings.fraudManagement.pipeline[]`. A stage is eligible for browser collection only when parent `settings.fraudManagement.enabled` and the stage's `enabled` are both `true`, the stage uses `cybersource-oca` or `cybersource-totalnet`, and its metadata has these four keys:

| Value           | Meaning                                                                          |
| --------------- | -------------------------------------------------------------------------------- |
| `provider`      | Pipeline-stage field, not metadata: `cybersource-oca` or `cybersource-totalnet`. |
| `merchantId`    | Fraud-execution merchant identity. It is not part of the browser `session_id`.   |
| `orgId`         | The Cybersource organization identifier for collection.                          |
| `sessionPrefix` | The backend-selected prefix for the provider correlation reference.              |
| `url`           | An approved HTTPS collection URL.                                                |

The hosted session snapshot includes only enabled, compatible stages with an approved collection URL and the required metadata. When more than one payment method applies before the card brand is known, deduplicate the applicable stages by `url`, `orgId`, `sessionPrefix`, and the reference used for that browser session.

## Correlation reference

The browser collector sends the Cybersource `session_id` as:

```
sessionPrefix + deviceFingerprint
```

The backend selects the prefix as follows:

| Provider               | Condition                                                          | `sessionPrefix`                                              |
| ---------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ |
| `cybersource-oca`      | Handy client, or the merchant payment method uses the Handy PayFac | `oca_handy`                                                  |
| `cybersource-oca`      | Neither Handy condition applies                                    | `oca_plexo`                                                  |
| `cybersource-totalnet` | Every case                                                         | The configured payment method `MerchantIdentificationNumber` |

The OCA selection is independent of environment. The Totalnet prefix is the payment method's configured MID even when fraud execution later resolves different credentials or merchant identity. The collection prefix is not the fraud-execution merchant ID.

## Hosted sessions

For checkout and tokenization sessions, Plexo owns the browser reference. Use the hosted session ID in compact GUID form, without hyphens, as `deviceFingerprint`; do not use the merchant `referenceId` as a fallback. The hosted frontend starts collection as soon as the validated session and targets are available, before card or wallet submission.

Collection waits at most three seconds from its start before payment submission continues under the merchant's existing fraud rules. A script-load event is not proof that Cybersource received a fingerprint. Collection failures and timeouts do not create automatic retry loops.

## Direct payments

For `POST /v1/payments`, the integration owns `browserDetails.deviceFingerprint`. It is optional and is preserved unchanged for card, stored-token, network-token, Google Pay, and Apple Pay payment inputs. Do not prepend `sessionPrefix` in the payment request: it is applied only when forming the browser collector's `session_id`. Do not substitute `referenceId`, and do not reuse a fingerprint from an earlier tokenization.

This synthetic stored-token request supplies a merchant-generated reference:

```json
{
  "merchantId": 12345,
  "referenceId": "order-fingerprint-demo-1001",
  "amount": {
    "total": 19.95,
    "currency": "USD"
  },
  "paymentMethod": {
    "source": "token",
    "paymentInstrument": {
      "token": "11111111-2222-3333-4444-555555555555"
    }
  },
  "browserDetails": {
    "ipAddress": "203.0.113.42",
    "userAgent": "Mozilla/5.0 (Synthetic integration example)",
    "deviceFingerprint": "merchant_browser_ref_01HZY9F6J8K2M4N6P8Q0R2S4T6"
  }
}
```

`deviceFingerprint` remains `merchant_browser_ref_01HZY9F6J8K2M4N6P8Q0R2S4T6` in the payment's browser details and downstream fraud context. The pipeline stage's `sessionPrefix` is not persisted into that value.

## Related resources

* [Payment Methods Setup Guide](/rest-api/merchant-configuration/payment-methods-setup.md)
* [Checkout Session Integration](/rest-api/sessions/checkout-session.md)
* [Tokenization Session Integration](/rest-api/sessions/tokenization-session.md)
* [Create a Payment](/rest-api/payments/payment-processing/create-payment.md)