> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Cybersource Decision Manager

> Screen payments with Cybersource Decision Manager in your Payrails workflow, receive review decisions and see the fields Payrails sends.

Screen payments with [Cybersource Decision Manager](https://www.cybersource.com/) before or after authorization. Payrails sends Decision Manager the order, customer, device and card details and maps its decision to a Payrails decision your workflow acts on. When Decision Manager holds a payment for manual review, Payrails waits for the review outcome and then continues the workflow.

## Supported operations

| Operation | Supported | Decision Manager API |
| - | - | - |
| Pre-authorization score | ✔ | Create decision |
| Post-authorization score | ✔ | Create decision |
| Review decisions | ✔ | Webhook for case management decisions |

Decision Manager returns its decision in the response. When it holds the payment for review, the **Fraud Check** step pauses until Cybersource sends the reviewer's decision by webhook.

## Decisions

| Decision Manager status | Payrails decision |
| - | - |
| `ACCEPTED` | `Allow` |
| `CHALLENGE` | `Challenge` |
| `PENDING_REVIEW`, `REVIEW` | `Review` |
| `REJECTED`, `DECLINED` | `Prevent` |

After a manual review, the reviewer's decision maps the same way: `ACCEPT` to `Allow`, `REJECT` to `Prevent` and `REVIEW` to `Review`. You set the rules and profiles that produce these decisions in your Decision Manager configuration at Cybersource.

## Before you begin

1. In the Cybersource Business Center, go to **Payment Configuration** → **Key Management** and generate a **REST - Shared Secret** key. Copy the key ID and the shared secret.
2. In the Payrails Portal, go to **Settings → Integrations** and select **Add instance**.
3. Select the workspaces where Cybersource should be available.
4. Select **Fraud** as the integration type, then **Cybersource** as the provider.
5. Enter your Cybersource details and save:

| Field | Description |
| - | - |
| **Merchant ID** | Your Cybersource merchant ID |
| **Key** | Your REST key ID. Payrails uses it to sign every request to Cybersource. |
| **Shared Secret Key** | Your REST shared secret |
| **Notifications Key ID** | The key ID of your Cybersource webhook signature key |
| **Notifications Secret Key** | The base64-encoded secret of your Cybersource webhook signature key. Payrails uses it to verify webhooks from Cybersource. |

6. In Cybersource, set up a webhook for Decision Manager case management decisions that posts to the Payrails notification URL of this integration, with the signature key you entered above.
7. Load the Cybersource provider in the [Payrails Web Fraud SDK](/docs/orchestration/checkout-sdks/payrails-web-fraud-sdk#cybersource) with your Cybersource organization ID and merchant ID, or pass the device fingerprint session ID from your own integration in `meta.risk.sessions`.
8. Add a **Fraud Check** step with your Cybersource integration to your workflow. See [Authorization with fraud screening](/docs/orchestration/workflow-studio/examples/authorization-with-fraud).

Payrails sends requests to the Cybersource test environment in test mode and to the live environment in live mode. Card payments must use the Payrails vault, because Payrails sends the card details through it.

## Request fields for Cybersource

Send these fields in the authorize request, in addition to the standard [authorize fields](/reference/authorizeaction). **Required** fields must be present for the score to succeed. Payrails sends **Optional** fields to Cybersource when you include them.

| Field | Status | Description |
| - | - | - |
| `meta.order` | Required | Payrails returns no decision when the order is missing. |
| `meta.customer` | Required | Payrails returns no decision when the customer is missing. |
| `meta.clientContext` | Required | Payrails returns no decision when the client context is missing. |
| `meta.risk` | Required | Payrails returns no decision when the risk object is missing. |
| `amount` | Required | Sent to Cybersource as the order total and currency. |
| `merchantReference` | Optional | Sent to Cybersource as the client reference code. Cybersource returns it in review webhooks. |
| `meta.risk.sessions` | Optional | An entry with `provider` set to `cybersource` and the device fingerprint session ID as `sessionId`. Payrails falls back to `meta.risk.sessionId`. |
| `meta.risk.merchantDefinedData` | Optional | Key-value pairs sent to Cybersource as merchant-defined data for your Decision Manager rules. |
| `meta.clientContext.ipAddress`, `host`, `userAgent`, `language` | Optional | Sent to Cybersource as the device IP address, host name, user agent and browser language. |
| `meta.clientContext.colorDepth`, `screenHeight`, `screenWidth`, `timeZoneOffset`, `javaEnabled`, `javaScriptEnabled`, `cookiesAccepted` | Optional | Sent to Cybersource as browser details. |
| `meta.order.billingAddress` | Optional | Sent to Cybersource as the bill-to name, address, phone and email. |
| `meta.order.deliveryAddress` | Optional | Sent to Cybersource as the ship-to name, address and phone. |
| `meta.order.lines` | Optional | Sent to Cybersource as the line items, with `id`, `name`, `description`, `quantity`, `unitPrice` and `totalTax`. |
| `meta.customer.identityCardNumber` | Optional | Sent to Cybersource as the customer ID and as a CPF personal identification. |
| `meta.customer.birthDate` | Optional | Sent to Cybersource as the customer's date of birth. |

For card payments, Payrails also sends the card number, BIN, network and expiry date from the instrument.

## Example authorize request

```json Authorize request theme={null}
{
  "amount": { "value": "249.90", "currency": "BRL" },
  "merchantReference": "order-58213",
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "card",
      "amount": { "value": "249.90", "currency": "BRL" }
    }
  ],
  "meta": {
    "customer": {
      "identityCardNumber": "12345678909",
      "birthDate": "1990-04-12"
    },
    "clientContext": {
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0 Safari/537.36",
      "language": "pt-BR"
    },
    "risk": {
      "sessions": [{ "provider": "cybersource", "sessionId": "c1f0a7e2-5b9d-4e3a-8f6c-2d4b7a9e1c05" }]
    },
    "order": {
      "lines": [
        {
          "id": "sku-771",
          "name": "Running shoes",
          "quantity": 1,
          "unitPrice": { "value": "249.90", "currency": "BRL" }
        }
      ],
      "billingAddress": {
        "name": "Ana",
        "lastName": "Souza",
        "email": "ana.souza@example.com",
        "street": "Rua Augusta",
        "doorNumber": "1500",
        "city": "São Paulo",
        "state": "SP",
        "postalCode": "01304-001",
        "country": { "code": "BR" }
      }
    }
  }
}
```


## Related topics

- [Fraud integrations](/docs/orchestration/fraud-integrations.md)
- [Cybersource](/docs/orchestration/integrations/cybersource.md)
- [API Credentials](/docs/account-setup/api-credentials.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.