HyperPay

Who should use this guideThis guide is intended for merchants who:

Use Payrails as a payment orchestrator
Use HyperPay for Visa, Mastercard, mada or Apple Pay
Have an active HyperPay merchant account

Create a HyperPay integration in Payrails

Log in to the Payrails portal.
Go to Settings → Integrations.
Select Add instance to create a new integration configuration.
Select the workspaces where this integration should be available.

About workspacesWorkspaces 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 Hyperpay.
Continue to the next step.

A screenshot showing HyperPay selected as the provider.

Step 3: Configure your HyperPay integration

What you’ll need from HyperPayBefore you begin, make sure you have your HyperPay entity IDs, access token and webhook decryption key. HyperPay provides them when it sets up your account.

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

A screenshot showing the integration instance name field.

Account details

In Payrails

Field	Value
Entity ID	Your HyperPay entity ID for 3D Secure payments
Entity ID with no 3DS requirement [MOTO]	Your HyperPay entity ID for payments without 3D Secure. Payrails uses it for Visa and Mastercard payments when you don’t force 3D Secure, and for recurring payments in SAR and JOD.
A flag to toggle whether notifications validate source or not	Leave it empty. If you enter `0`, Payrails ignores HyperPay notifications.

A screenshot showing the HyperPay account details fields.

Credentials

In Payrails

Field	Value
API key	Your HyperPay access token
Decryption key	Your HyperPay webhook decryption key. Payrails uses it to decrypt notifications from HyperPay.

Payrails sends requests to the HyperPay test environment in test mode and to the live environment in live mode, so use the credentials for the matching environment.

A screenshot showing the HyperPay credential fields.

Payment methods

In Payrails

Select Card, Apple Pay or both.

A screenshot showing the HyperPay payment method selection.

Webhooks or notifications

Payrails uses provider webhooks or notifications to receive asynchronous payment status updates.

Create webhooks in the same mode (test or live) as your Payrails integration.

In Payrails

Copy the Notification URL shown under Account configuration at the top of the integration form.

In HyperPay

Send the Payrails notification URL to HyperPay, and ask them to set up a webhook for payments on your entity IDs.
When HyperPay confirms, check that the decryption key they give you matches the Decryption key in Payrails.

Request fields for HyperPay

Send these fields in the authorize request 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 HyperPay when you include them. For more about meta fields, refer to Meta fields.

Field	Status	Description
`amount`	Required	Sent to HyperPay with two decimals, with the currency. Use SAR, JOD or IQD, or send a full billing address.
`meta.customer.email`	Required	Sent as the customer email. If you send `meta.customer.reference` instead, Payrails builds an email address from it.
`instrument.data.network`	Required	Visa, Mastercard or mada.
`meta.risk.threeDSMode`	Required	Set to `Force` for mada cards. For Visa and Mastercard, `Force` runs 3D Secure on your Entity ID. Without it, Payrails sends the payment on your MOTO entity ID.
`meta.clientContext`	Optional	When you force 3D Secure. Send `userAgent`, `acceptHeader`, `language`, `colorDepth`, `screenHeight`, `screenWidth`, `timeZoneOffset` and `javaEnabled`, sent as browser details.
`meta.customer.name`, `meta.customer.lastName`	Optional	Sent as the customer’s given name and surname.
`instrument.holderName`	Optional	Sent as the card holder.
`meta.order.billingAddress`	Optional	Sent as the billing street, city, state, postal code and country.
`meta.order.softDescriptor`	Optional	Sent as the descriptor.
`merchantReference`	Optional	Sent as the merchant transaction ID.
`instrument.storeInstrument`	Optional	Stores the card with HyperPay for later payments.

Enable the integration

In Payrails

Select Save account to enable the integration.
Confirm the integration shows as Enabled.

Your HyperPay integration is now ready to process payments.

Next steps

Run a test card payment in the HyperPay test environment.
Verify that:
- The payment appears in HyperPay.
- The payment status updates correctly in Payrails.
Once verified in test mode, repeat the setup in live mode.

→ Continue to: Test a payment

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Create a HyperPay integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider