> ## 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.

# Signifyd

> Screen orders with Signifyd in Payrails, report fulfilment, returns and chargebacks, and see the request fields Signifyd requires.

Screen orders with [Signifyd](https://www.signifyd.com/) before or after authorization. Payrails sends Signifyd a checkout before authorization or a sale after it, and maps Signifyd's checkpoint action to a Payrails decision your workflow acts on. Payrails also reports fulfilment, returns, cancellations and chargebacks to Signifyd.

## Supported operations

| Operation | Supported | Signifyd endpoint |
| - | - | - |
| Pre-authorization score | ✔ | Checkouts |
| Post-authorization score | ✔ | Sales, with the decision delivered in the response |
| Order updates | ✔ | `fulfillments` and `returns/records` |
| Dispute reporting | ✔ | Chargebacks |

Signifyd returns its decision in the response, so the Fraud Check step completes straight away.

## Decisions

| Signifyd checkpoint action | Payrails decision |
| - | - |
| `ACCEPT` | `Allow` |
| `REJECT` | `Prevent` |
| `HOLD` | `Review` |
| `CREDIT` | `Review` |
| Any other | `NoDecision` |

## Before you begin

1. In the Payrails Portal, go to **Settings → Integrations** and select **Add instance**.
2. Select the workspaces where Signifyd should be available.
3. Select **Fraud** as the integration type, then **Signifyd** as the provider.
4. Enter your Signifyd credentials and save:

| Field | Description |
| - | - |
| **API Key** | Your Signifyd API key. Use the key of your Signifyd sandbox team to test. |
| **Team ID** | Optional. Only needed when several Signifyd teams share your API key. |

5. Pass the session ID from Signifyd's device fingerprinting script in `meta.risk.sessions`.
6. Add a **Fraud Check** step with your Signifyd integration to your workflow. See [Authorization with fraud screening](/docs/orchestration/workflow-studio/examples/authorization-with-fraud).

## Request fields for Signifyd

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 Signifyd when you include them.

| Field | Status | Description |
| - | - | - |
| `merchantReference` | Required | Set on the execution. Sent to Signifyd as the order ID. |
| `amount` | Required | Sent to Signifyd as the purchase total and transaction amount. |
| `meta.order.lines` | Required | At least one line. Sent to Signifyd as products, with `id`, `name`, `quantity`, `unitPrice`, `categoryId`, `description`, `weight`, product links and whether the product is digital. |
| `meta.customer.email` | Optional | Needed to send the customer account to Signifyd. Sent as the account and confirmation email. |
| `meta.customer.name` | Optional | Sent to Signifyd as the account username. Payrails uses the email when it's missing. |
| `meta.customer.reference` | Optional | Sent to Signifyd as the account ID and number. |
| `meta.customer.phone` | Optional | Sent to Signifyd as the account and confirmation phone. |
| `meta.customer.createdAt`, `meta.customer.updatedAt` | Optional | Sent to Signifyd as the account creation and last update dates. |
| `meta.customer.previousPurchaseCount` | Optional | Sent to Signifyd as the aggregate order count. |
| `meta.customer.previousOrders` | Optional | Payrails adds up the amounts and sends the total to Signifyd as the aggregate order value. |
| `meta.order.createdAt` | Optional | Sent to Signifyd as the purchase creation time. Payrails uses the execution creation time when it's missing. |
| `meta.order.deliveryAddress` | Optional | Sent to Signifyd as the shipment destination. Payrails uses the billing address when it's missing. |
| `meta.order.billingAddress` | Optional | Sent to Signifyd as the billing address of the payment. |
| `meta.order.fulfillmentMethod` | Optional | Sent to Signifyd as the shipment fulfilment method, for example `STANDARD_SHIPPING`. Left out for digital orders. |
| `meta.order.shipmentReference` | Optional | Sent to Signifyd as the shipment ID. |
| `meta.order.shipping` | Optional | Sent to Signifyd as the total shipping cost. |
| `meta.order.totalDiscount` | Optional | Sent to Signifyd as the discount amount. |
| `meta.clientContext.ipAddress` | Optional | Sent to Signifyd as the device IP address. |
| `meta.risk.sessions` | Optional | An entry with `provider` set to `signifyd` and the device session ID as `sessionId`. Payrails falls back to `meta.risk.sessionId` when there's no Signifyd entry. |
| `meta.risk.skipFraudDecision` | Optional | Set it to `true` for an order you already trust. Payrails then sends the order to Signifyd for information only, with no fraud coverage, and Signifyd accepts it by policy. |

Payrails sends the payment details from the instrument, such as the card BIN, last four digits, brand and expiry, or the bank account. For a post-authorization score, Payrails also sends the PSP reference as the transaction ID, the authorization result and the 3D Secure result.

## Send order updates

Add a **Fraud Update** step after each lifecycle action and set its `orderStatus`. Payrails picks the Signifyd event from the status.

| Payrails order status | Signifyd event | Status |
| - | - | - |
| `fullyShipped`, `fullyDelivered` | Fulfillment | `COMPLETE` |
| `partiallyShipped`, `partiallyDelivered` | Fulfillment | `PARTIAL` |
| `fullyReplaced`, `partiallyReplaced` | Fulfillment | `REPLACEMENT` |
| `merchantCancelled`, `customerCancelled` | Return record | `CANCELED` |
| `fullyReturned`, `partiallyReturned` | Return record | `REFUNDED` |

## Report disputes

Payrails reports each chargeback on an order to Signifyd, with its amount, reason and card network. Payrails reports fraud alerts and retrieval requests at the `RETRIEVAL` stage, and every other dispute at the `CHARGEBACK` stage.

## Example authorize request

```json Authorize request theme={null}
{
  "amount": { "value": "149.00", "currency": "EUR" },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "card",
      "amount": { "value": "149.00", "currency": "EUR" }
    }
  ],
  "meta": {
    "customer": {
      "reference": "customer-4410",
      "name": "Jonas Weber",
      "email": "jonas.weber@example.com",
      "createdAt": "2024-02-08T11:20:00Z"
    },
    "clientContext": {
      "ipAddress": "203.0.113.10"
    },
    "risk": {
      "sessions": [{ "provider": "signifyd", "sessionId": "5f2e9b7c-1d84-4a6e-b0c3-9e7a2d4f6c18" }]
    },
    "order": {
      "createdAt": "2026-10-05T09:00:00Z",
      "fulfillmentMethod": "STANDARD_SHIPPING",
      "lines": [
        {
          "id": "sku-3381",
          "name": "Leather backpack",
          "quantity": 1,
          "unitPrice": { "value": "149.00", "currency": "EUR" },
          "product": { "type": "physical" }
        }
      ],
      "deliveryAddress": {
        "name": "Jonas",
        "lastName": "Weber",
        "street": "Leopoldstraße",
        "doorNumber": "45",
        "city": "München",
        "postalCode": "80802",
        "country": { "code": "DE" }
      }
    }
  }
}
```


## Related topics

- [Payrails Web Fraud SDK](/docs/orchestration/checkout-sdks/payrails-web-fraud-sdk.md)
- [Fraud integrations](/docs/orchestration/fraud-integrations.md)


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