> ## 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. # HiPay > Set up a HiPay card integration in the Payrails Portal, including private and public credentials, and configure HiPay Console notifications. ![HiPay logo](https://assets.payrails.io/img/logos/hipay/logo-full-bleed.svg) > [!NOTE] > > **Who should use this guide** > > This guide is intended for merchants who: > > * Use **Payrails** as a payment orchestrator > * Use **HiPay** to accept **card** payments in Europe > > HiPay is a server-to-server card connector with no hosted payment page. Your shopper enters card details directly in your checkout through the Payrails SDK's secure fields, and a redirect to HiPay happens only for the 3DS challenge, when one is required. ## Create and configure a HiPay integration in Payrails Follow these steps to set up HiPay: 1. Log in to the **Payrails** portal. 2. Go to **Settings → Integrations → Payments**. 3. Select **Add instance** to create a new HiPay 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** and continue to the next step. ![A screenshot showing the integration type selection form.](https://mintcdn.com/payrails-42074109/To59SEkYYPq19nmx/images/docs/orchestration/integrations/shared/integration-type-selection.png?fit=max\&auto=format\&n=To59SEkYYPq19nmx\&q=85\&s=2a1afe79c3ac25f3a8437846a1d36ffb) ## Step 2: Choose the provider Select **HiPay** and continue to the next step. ![Payrails provider selection set to HiPay](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-01.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=93196775a1e06e99ef220d5d053a956a) ## Step 3: Configure your HiPay integration > [!TIP] > > **What you'll need from HiPay** > > Before you begin, make sure you have access to your **HiPay Console** and the following. HiPay uses two separate credential pairs for two separate hosts, so copy each into the matching field: > > * **Private credentials** — **Username** and **Password** (used to authorize, capture, cancel, and refund payments) > * **Secret Passphrase** (used to verify HiPay's notification signatures) > * **Public credentials** — **Username** and **Password** (used only to tokenize the card) ### Integration instance name > An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for each provider based on region, currency, or business needs. Choose a clear, consistent name, since it's used in routing. **In Payrails** * Enter an **Instance name** for your integration. ![Payrails integration instance name field for HiPay](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-02.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=a45518723d96c214722f6f5d9427cc1a) ### Private credentials **In HiPay** * Log in to the HiPay Console (**stage** or **production**). * Switch to the "Old Interface," since it has more options. ![HiPay Console login screen](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-03.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=a7b55bcac3f374e36b0b3052324d7c14) ![HiPay Console toggle for switching to the Old Interface](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-04.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=2e1b64b7a3f94fe7faffee685b6a1a3c) * Go to **Integration → Security Settings** and copy your **private Username** and **Password**. ![HiPay Console security settings showing private username and password fields](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-05.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=24d81b4c834197ec5282bae5071649ba) **In Payrails** * Paste the values into the **Private username** and **Private password** fields. ![Payrails private username and password fields for HiPay](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-06.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=4a1e722816bb5244765b77af553c8f87) ### Secret Passphrase **In HiPay** * Still in **Integration → Security Settings**, copy your **Secret Passphrase**. * Set the **Hashing Algorithm** to **SHA-256**. ![HiPay Console security settings showing secret passphrase and hashing algorithm fields](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-07.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=381b1d15ea995d585d7612d245bbb422) **In Payrails** * Paste the value into the **Secret Passphrase** field. ![Payrails secret passphrase field for HiPay](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-08.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=fa0f47cee83cdca7a076cc5306d2a39e) Store your merchant secret passphrase securely. Payrails uses it to verify that notifications genuinely come from HiPay. ### Public credentials **In HiPay** * In the same **Security Settings** section, copy your **public Username** and **Password**. ![HiPay Console security settings showing public username and password fields](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-09.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=2f739a6faf882a7c72d33da0088445e2) **In Payrails** * Paste the values into the **Public username** and **Public password** fields. ![Payrails public username and password fields for HiPay](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-10.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=bbb0a86b18e76ae72a7a0ffc90fd9451) > [!NOTE] > > The public credentials are only used to tokenize the card on HiPay's vault > host. The raw card number never reaches Payrails or your systems: it is sent > > as a vault placeholder through the Payrails vault proxy. ### Payment methods **In Payrails** * Under **Payment methods**, enable **Card**. ## Configure notifications in the HiPay Console Unlike some providers, HiPay requires you to configure the notification (webhook) URL yourself, on the HiPay side. **In Payrails** * After saving your HiPay configuration, copy the generated **notification URL** from the provider config. **In HiPay** 1. In the HiPay Console, go to **Integration → Notifications**. 2. Paste the Payrails **notification URL**. 3. Select the transaction statuses to be notified on. At minimum, enable: `109`–`115`, `116`–`119`, `124`–`126`, `163`, `165`, and `173`–`175`. ![HiPay Console notification settings with transaction status selection](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-11.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=b5c1f23153c7b7f0a1076544a8ff7707) 4. Enable the `operation[...]` fields in the notification settings. These are off by default. ![HiPay Console notification settings showing the operation fields toggle](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/hipay-image-12.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=61fccd606b9e3c9c01b8f5b242e78870) > [!WARNING] > > Enable the `operation[...]` fields — this step is required. Without them, > Payrails cannot match partial captures and partial refunds back to the correct > operation, and notifications for those operations may be dropped. ## Request fields for HiPay 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 HiPay 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 HiPay as the amount and currency. | | `merchantReference` | Required | Sent as the order ID. | | `instrument.securityCode` | Required | New cards. Sent as the card security code. | | `instrument.holderName` | Optional | Sent as the card holder. Payrails uses `meta.customer.name` and `lastName` when it's missing. | | `meta.order.description` | Optional | Sent as the payment description. | | `meta.customer.name`, `lastName`, `email`, `phone`, `birthDate`, `reference` | Optional | Sent as the customer details. | | `meta.customer.createdAt`, `updatedAt`, `previousPurchaseCount`, `previousOrders` | Optional | Sent as account information for 3D Secure. | | `meta.order.billingAddress` | Optional | Sent as the billing address. Its name, email and phone replace the customer's. | | `meta.order.deliveryAddress` | Optional | Sent as the shipping address. | | `meta.order.shippingType`, `deliveryDate`, `lines` | Optional | Sent as the merchant risk statement for 3D Secure. | | `meta.order.softDescriptor` | Optional | Sent as the soft descriptor. | | `meta.order.shipping`, `meta.order.totalTax` | Optional | Sent as the shipping and tax amounts. | | `meta.clientContext` | Optional | Browser fields, `ipAddress` and `deviceFingerprint`, sent as browser and device details. | | `meta.risk.threeDSMode` | Optional | `Force` or `Skip`. Sets the 3D Secure authentication indicator. | | `meta.subscription.chargeFrequency` | Optional | When you save the card. Sent as the recurring frequency. | HiPay accepts Visa, Mastercard, Maestro, American Express and Cartes Bancaires cards. *** ## Enable the integration **In Payrails** * Select **Save account** to save the configuration and enable the integration. * The **Enabled** status confirms that the HiPay integration is active. Your HiPay integration is now ready to process payments. ## Next steps 1. Run a test payment in **test mode** using a HiPay test card, in **EUR**: * **Frictionless:** Visa `4111 1111 1111 1111`, any near-future expiry, any three-digit CVV. * **3DS challenge:** Visa `4242 4242 4242 4242`, any near-future expiry, any three-digit CVV — complete the challenge on HiPay's page. 2. Verify that: * The payment appears in your **HiPay Console**. * 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 - [HiPay](https://docs.payrails.com/docs/integrations/data-sources/hipay.md) - [Payrails Web Fraud SDK](https://docs.payrails.com/docs/sdks/fraud-sdk.md) - [Connect your data sources](https://docs.payrails.com/docs/integrations/data-sources.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.