Moyasar Invoice Synchronization

Complete guide to invoice synchronization between Flexprice and Moyasar

Overview

Moyasar integration in Flexprice syncs invoices to Moyasar and generates a payment link (Moyasar invoice URL) for each synced invoice.

Synchronization Flow

The sync process is one-way (Flexprice → Moyasar) and works as follows:

How it Works

1. Trigger

   An invoice sync is triggered (automatically).

2. Creation

   Flexprice creates an invoice object in Moyasar using the secret_key.

3. Link Generation

   Moyasar returns a url (the payment page).

4. Metadata Update

   Flexprice saves the Moyasar invoice ID and payment URL in the invoice metadata.

Invoice Data Model

Flexprice Invoice Structure

{
  "id": "inv_123",
  "amount": "100.00",
  "currency": "SAR",
  "metadata": {
    "moyasar_invoice_id": "inv_moy_xyz",
    "moyasar_invoice_url": "https://moyasar.com/i/inv_moy_xyz"
  }
}

Moyasar Invoice Structure

{
  "id": "inv_moy_xyz",
  "status": "initiated",
  "amount": 10000,
  "currency": "SAR",
  "description": "Invoice for Premium Plan",
  "url": "https://moyasar.com/i/inv_moy_xyz",
  "metadata": {
    "flexprice_invoice_id": "inv_123"
  }
}

Sync Configuration

The following fields are mapped during sync:

Field	Flexprice → Moyasar	Notes
amount	✅	Converted to smallest unit (e.g., Halalah)
currency	✅	Passed as-is (e.g., SAR)
description	✅	Summary of line items
metadata	✅	Includes flexprice_invoice_id for tracking

Payment Flow & Webhooks

Payment Journey

1. User pays

   User clicks the moyasar_invoice_url.

2. Processing

   Payment is processed on Moyasar’s hosted page.

3. Webhook

   Moyasar sends a payment_paid webhook.

4. Reconciliation

   Flexprice receives the webhook, finds the invoice via the metadata/mapping, and updates the invoice status to PAID.

Error Handling

Error	Cause
Moyasar connection not configured	No active Moyasar connection found for the tenant/env.
Currency not supported	Invoice currency (e.g., INR) not supported by your Moyasar account.
Invalid amount	Amount must be positive.

Testing

1. Create invoice

   Create a Flexprice invoice.

2. Trigger sync (Automatically)

   Trigger the sync to Moyasar.

3. Check metadata

   Check invoice metadata for moyasar_invoice_url.

4. Test payment

   Open the URL and pay using a Test Card.

Test Cards (Moyasar Sandbox)

Number	Expiry	CVC	Result
4111 1111 1111 1111	Future	123	Success
4000 0000 0000 0002	Future	123	Failure