> ## 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 > Connect Cybersource to Payrails for cards and Apple Pay, covering your merchant ID, REST API keys and acquirer details for 3D Secure. ![Cybersource logo](https://assets.payrails.io/img/logos/cybersource/logo-full-bleed.svg) > [!NOTE] > > **Who should use this guide** > > This guide is intended for merchants who: > > * Use **Payrails** as a payment orchestrator > * Use **Cybersource** for card and Apple Pay processing > * Have access to the Cybersource Business Center *** ## Create a Cybersource integration in Payrails 1. Log in to the **Payrails** portal. 2. Go to **Settings** → **Integrations**. 3. Select **Add instance** to create a new integration configuration. 4. Select the **workspaces** where this integration should be available. > [!NOTE] > > **About workspaces** > > Workspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces. *** ## Step 1: Choose the integration type * Select **Payment**. * Continue to the next step. *** ## Step 2: Choose the provider * Select **Cybersource**. * Continue to the next step. ![A screenshot showing Cybersource selected as the provider.](https://mintcdn.com/payrails-42074109/mvpmUCWsmtHcC_pw/images/docs/cybersource-image-01.png?fit=max\&auto=format\&n=mvpmUCWsmtHcC_pw\&q=85\&s=56dbac70d6abb038415ea2b0ce854d97) *** ## Step 3: Configure your Cybersource integration > [!TIP] > > **What you'll need from Cybersource** > > Before you begin, make sure you can log in to the Cybersource Business Center. You'll copy your merchant ID and create a REST shared secret key there. If you use Payrails 3D Secure, get your acquirer BIN and acquirer merchant ID for each card network from your acquirer. *** ### Integration instance name > An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, as it is used in routing. **In Payrails** * Enter an **Instance name** for your integration, for example `merchant_cybersource`. ![A screenshot showing the integration instance name field.](https://mintcdn.com/payrails-42074109/145W1v58K5wnDMNC/images/docs/orchestration/integrations/shared/integration-instance-name.png?fit=max\&auto=format\&n=145W1v58K5wnDMNC\&q=85\&s=470be58979509680650b0cbf8b5eecc4) *** ### Payment methods **In Payrails** * Select **Card**, **Apple Pay** or both. ![A screenshot showing the Cybersource payment method selection.](https://mintcdn.com/payrails-42074109/mvpmUCWsmtHcC_pw/images/docs/cybersource-image-02.png?fit=max\&auto=format\&n=mvpmUCWsmtHcC_pw\&q=85\&s=ce98c8df27fe37a3be838e876a86fa35) *** ### Account details **In Payrails** | Field | Value | | :- | :- | | **Merchant ID** | Your Cybersource merchant ID | | **Partner solution ID** | Optional. The partner solution ID Cybersource gave you, if any. Payrails sends it with every request. | | **Acquirer Bin Visa**, **Acquirer Bin Mastercard** | Optional. The acquirer BIN for each card network. Payrails uses them to run 3D Secure. | | **Acquirer Merchant ID Visa**, **Acquirer Merchant ID Mastercard**, **Acquirer Merchant ID Amex** | Optional. The merchant ID your acquirer assigned for each card network. Payrails uses them to run 3D Secure. | | **Acquirer Bin Amex** | Not needed. Leave it empty. | ![A screenshot showing the Cybersource account details fields.](https://mintcdn.com/payrails-42074109/mvpmUCWsmtHcC_pw/images/docs/cybersource-image-03.png?fit=max\&auto=format\&n=mvpmUCWsmtHcC_pw\&q=85\&s=74521145eb4d8bf8f3067e4efbd5e316) ![A screenshot showing the Cybersource account details fields.](https://mintcdn.com/payrails-42074109/mvpmUCWsmtHcC_pw/images/docs/cybersource-image-04.png?fit=max\&auto=format\&n=mvpmUCWsmtHcC_pw\&q=85\&s=66fd21bd02e590af23c10cb7c372e151) *** ### Credentials **In Cybersource** 1. In the Business Center, go to **Payment Configuration** → **Key Management**. 2. Generate a **REST - Shared Secret** key. 3. Copy the key ID and the shared secret. **In Payrails** | Field | Value | | :- | :- | | **Key ID** | Your Cybersource REST key ID | | **Shared secret** | Your Cybersource REST shared secret. Payrails signs every request with it. | Payrails sends requests to the Cybersource test environment in test mode and to the live environment in live mode, so use the keys for the matching environment. ![A screenshot showing the Cybersource credential fields.](https://mintcdn.com/payrails-42074109/mvpmUCWsmtHcC_pw/images/docs/cybersource-image-05.png?fit=max\&auto=format\&n=mvpmUCWsmtHcC_pw\&q=85\&s=1912f9463c37a600e3cf41e6c4d451ae) *** ### Payment status updates Payrails checks the status of pending Cybersource payments until they reach a final state, so there's no webhook to set up. *** ## Request fields for Cybersource Send these fields in the [authorize request](https://docs.payrails.com/reference/authorizeaction.md) for card payments, in addition to the standard authorize fields. **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to Cybersource when you include them. For more about meta fields, refer to [Meta fields](https://docs.payrails.com/docs/orchestration/meta-fields.md). | Field | Status | Description | | :- | :- | :- | | `amount` | Required | Sent to Cybersource as the total amount and currency. | | `merchantReference` | Optional | Sent as the client reference code. | | `meta.customer.name`, `lastName`, `email`, `phone` | Optional | Sent in the bill-to details. | | `meta.order.billingAddress` | Optional | Sent as the bill-to city, state, postal code and country. | | `instrument.networkTransactionReference` | Optional | Merchant-initiated payments only. Sent as the previous transaction ID. | *** ## Enable the integration **In Payrails** * Select **Save account** to enable the integration. * Confirm the integration shows as **Enabled**. Your **Cybersource** integration is now ready to process payments. *** ## Next steps 1. Run a test card payment in the Cybersource test environment. 2. Verify that: * The payment appears in the Business Center. * The payment status updates correctly in Payrails. 3. Once verified in test mode, repeat the setup in live mode. → Continue to: [Test a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/test-payments.md) ## Related topics - [Cybersource Decision Manager](https://docs.payrails.com/docs/integrations/fraud-prevention-providers/cybersource.md) - [Payrails Web Fraud SDK](https://docs.payrails.com/docs/sdks/fraud-sdk.md) - [Fraud prevention providers](https://docs.payrails.com/docs/integrations/fraud-prevention-providers.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.