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

# Moyasar

> Connect Moyasar to Payrails for cards, Apple Pay and Google Pay, covering your secret key, webhook secret token and webhook setup.

<picture noZoom>
  ![Moyasar logo](https://assets.payrails.io/img/logos/moyasar/logo-full-bleed.svg)
</picture>

> [!NOTE]
>
> **Who should use this guide**
>
> This guide is for merchants who:
>
> * Use **Payrails** as a payment orchestrator
> * Use **Moyasar** for card and wallet processing in Saudi Arabia
> * Have an active Moyasar account

***

## Create a Moyasar integration in Payrails

1. Log in to the **Payrails** portal.
2. Go to **Settings** → **Integrations**.
3. Select **New integration**.

***

## Step 1: choose the provider

* Search for **Moyasar** and select it.
* Select **Next step**.

![A screenshot showing Moyasar selected as the provider.](https://mintcdn.com/payrails-42074109/bCR3XJDY0GDYZu7m/images/docs/moyasar-image-01.png?fit=max\&auto=format\&n=bCR3XJDY0GDYZu7m\&q=85\&s=f58fd3f30b09da8616375b11c148b42e)

***

## Step 2: enter the basic information

The integration type is **Payment**.

> An integration instance is a specific payment provider setup in Payrails. Create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, because Payrails uses it in routing.

**In Payrails**

* Enter an **Integration name**, for example `merchant_moyasar`.
* Select the **workspaces** where this integration should be available.
* Select **Next step**.

![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)

> [!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 3: enter the account information

> [!TIP]
>
> **What you'll need from Moyasar**
>
> Before you begin, collect these from your Moyasar dashboard:
>
> * Your secret API key, from **Settings** → **API Keys**. Refer to the Moyasar guide to [get your API keys](https://docs.moyasar.com/docs/guides/dashboard/get-your-api-keys).
> * A secret token for the Payrails webhook. You choose it when you create the webhook in [Webhooks or notifications](#webhooks-or-notifications).

### Credentials

**In Payrails**

| Field | Value |
| :- | :- |
| **Secret Key** | Your Moyasar secret API key. Payrails uses it to authenticate every request. |
| **Webhook Secret Token** | The secret token of the Payrails webhook in your Moyasar dashboard. Payrails rejects webhooks that don't carry it. |

The key prefix sets the mode: `sk_test_` for test mode and `sk_live_` for live mode.

![A screenshot showing the Moyasar credentials and payment method fields.](https://mintcdn.com/payrails-42074109/bCR3XJDY0GDYZu7m/images/docs/moyasar-image-02.png?fit=max\&auto=format\&n=bCR3XJDY0GDYZu7m\&q=85\&s=9fc4c01c7916fe7339385e411b307200)

***

### Payment methods

**In Payrails**

* Select **Card**, **Apple Pay**, **Google Pay**, or any combination.

For Apple Pay, also complete the [Apple Pay setup](https://docs.payrails.com/docs/integrations/payment-methods/apple-pay) in Payrails.

***

### Webhooks or notifications

Moyasar sends payment events to a webhook. Create one that points to Payrails. The **Webhook** card on this step shows the notification URL. Copy it before you enable the integration.

![A screenshot showing the Webhook card that holds the Moyasar notification URL.](https://mintcdn.com/payrails-42074109/bCR3XJDY0GDYZu7m/images/docs/moyasar-image-03.png?fit=max\&auto=format\&n=bCR3XJDY0GDYZu7m\&q=85\&s=d4e755487caa35ae41f36300526275cc)

**In Moyasar**

1. In your Moyasar dashboard, go to **Settings** → **Webhooks**.
2. Create a webhook with the notification URL from Payrails, a secret token of your choice, and the payment events.
3. Select these events: `payment_paid`, `payment_authorized`, `payment_failed`, `payment_captured`, `payment_refunded` and `payment_voided`.

**In Payrails**

* Enter the same secret token in **Webhook Secret Token**.

Moyasar sends a `webhook_verification` event to confirm the URL, and Payrails verifies the webhook with your secret key straight away. If you select **Verify** on the webhook in the Moyasar dashboard and Moyasar asks for a one-time code, you don't need to enter it. Refresh the page and the webhook shows as verified.

***

## Request fields for Moyasar

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 Moyasar 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 Moyasar as the amount in halalas and the currency. |
| `meta.customer.name` | Optional | Sent as the cardholder name when the card has no holder name. |
| `meta.customer.lastName` | Optional | Sent with the first name as the cardholder name. |
| `meta.order.description` | Optional | Sent as the payment description. |
| `meta.order.softDescriptor` | Optional | Sent as the statement descriptor on card and saved-card payments. |
| `meta.tags` | Optional | Sent to Moyasar as metadata. Payrails adds `payrails_payment_id` and `merchant_reference`, which replace a tag with the same name. |
| `meta.risk.threeDSMode` | Optional | `Force` turns 3D Secure on and `Skip` turns it off. Without it, Moyasar uses 3D Secure on a new card and skips it on a saved card. |
| `merchantReference` | Optional | Sent to Moyasar as the `merchant_reference` metadata value. |

***

## Enable the integration

**In Payrails**

* Select **Enable integration**.
* Confirm the integration shows as **Enabled**.
* Add the payment method as a payment option in your workflow. For the steps, refer to [Set up payment methods](https://docs.payrails.com/docs/integrations/payment-methods/set-up-payment-methods.md).

Your **Moyasar** integration is now ready to process payments.

***

## Next steps

1. Run a test payment using a Moyasar [test card](https://docs.moyasar.com/docs/guides/card-payments/test-cards).
2. Verify that:
   * The payment appears in the Moyasar dashboard.
   * The payment status updates correctly in Payrails.
3. Once verified in test mode, repeat the setup with your live key.

→ Continue to [test a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/test-payments.md).


## Related topics

- [Cards](https://docs.payrails.com/docs/integrations/payment-methods/cards.md)
- [Payment providers](https://docs.payrails.com/docs/integrations/payment-providers.md)


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