Moyasar PHP

A simple, expressive PHP client for the Moyasar payment gateway.

This package provides a clean interface for working with Moyasar's Invoices and Payments APIs in any PHP 8.2+ application. It's framework-agnostic and works great with Laravel, Symfony, or plain PHP.

Requirements

• PHP 8.2+
• Saloon ^4.0
• Saloon Pagination Plugin ^2.3

Installation

Install via Composer:

composer require hamoda-dev/moyasar-php

That's it. No service providers to register, no config files to publish. The package is framework-agnostic — use it in Laravel, Symfony, Slim, or plain PHP.

Quick Start

Grab your secret key from the Moyasar dashboard, then:

use HamodaDev\Moyasar\Moyasar;
use HamodaDev\Moyasar\Invoice\DTO\CreateInvoiceDTO;
 
$moyasar = new Moyasar(
    baseUrl: 'https://api.moyasar.com/v1',
    apiKey:  getenv('MOYASAR_SECRET_KEY'),
);
 
// Create an invoice and send the customer to the hosted payment page
$invoice = $moyasar->invoice()->create(new CreateInvoiceDTO(
    amount:      2500,                 // 25.00 SAR — always in the smallest unit
    currency:    'SAR',
    description: 'Order #1234',
    callbackUrl: 'https://example.com/webhooks/moyasar',
));
 
header("Location: {$invoice->url}");

Three lines to take a payment. No Guzzle, no array-shuffling, no JSON decoding.

Recommended Environment Setup

Keep credentials out of your code:

MOYASAR_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxx
MOYASAR_BASE_URL=https://api.moyasar.com/v1

Warning

Never commit API keys to version control. Use environment variables, a secrets manager, or your framework's config system. Treat your secret key like a password.

Tip

Moyasar issues separate test (sk_test_...) and live (sk_live_...) keys. Use the test key in development and staging — you can run real payment flows against test cards without charging anyone.

---

Invoices

Invoices are the fastest way to accept a payment: you create one, send the customer to invoice->url, and Moyasar handles the entire checkout UI for you.

Create an Invoice

use HamodaDev\Moyasar\Invoice\DTO\CreateInvoiceDTO;
 
$invoice = $moyasar->invoice()->create(new CreateInvoiceDTO(
    amount:      2500,
    currency:    'SAR',
    description: 'Order #1234',
    callbackUrl: 'https://example.com/webhooks/moyasar',
    successUrl:  'https://example.com/payment/success',
    backUrl:     'https://example.com/payment/cancel',
    metadata:    ['order_id' => '1234'],
));
 
echo $invoice->url;     // Hosted payment page — redirect your user here
echo $invoice->id;      // Store this alongside your order
echo $invoice->status;  // "initiated" for a fresh invoice

Parameter	Type	Required	What it's for
amount	int	Yes	Smallest currency unit (halalas for SAR, cents for USD)
currency	string	Yes	ISO 4217 code (SAR, USD, ...)
description	string	Yes	Shown to the customer on the payment page
callbackUrl	?string	No	Webhook URL — Moyasar POSTs here when payment status changes
successUrl	?string	No	Where to redirect after a successful payment
backUrl	?string	No	Where to redirect if the customer cancels
expiredAt	?string	No	ISO 8601 — invoice auto-expires after this
metadata	?array	No	Arbitrary key-value data — perfect for your internal IDs

Prefer building DTOs from incoming request data? Use the array factory:

$dto = CreateInvoiceDTO::fromArray($request->validated());
$invoice = $moyasar->invoice()->create($dto);

Retrieve an Invoice

$invoice = $moyasar->invoice()->get('invoice_12345');
 
if ($invoice->status === 'paid') {
    // Fulfill the order
}

List Invoices (with Pagination)

Moyasar returns invoices in pages. The SDK's paginator handles page-walking for you — no manual ?page=N tracking:

$paginator = $moyasar->invoice()->list()->paginate($moyasar);
 
while ($paginator->hasMorePages()) {
    foreach ($paginator->items() as $invoice) {
        echo "{$invoice->id} — {$invoice->status}\n";
    }
 
    $paginator = $paginator->nextPage();
}

Tip

Every item yielded by items() is a fully-typed InvoiceDTO. Your IDE will autocomplete ->id, ->status, ->amount, and every other field.

Update an Invoice

Only metadata is updatable after creation — use this to attach internal context as your order progresses:

use HamodaDev\Moyasar\Invoice\DTO\UpdateInvoiceDTO;
 
$moyasar->invoice()->update('invoice_12345', new UpdateInvoiceDTO(
    metadata: [
        'order_id'     => '1234',
        'fulfilled_at' => now()->toIso8601String(),
    ],
));

Bulk-Create Invoices

Need to send 50 invoices for a batch of orders? One request, one round-trip:

$result = $moyasar->invoice()->bulkCreate([
    new CreateInvoiceDTO(amount: 1000, currency: 'SAR', description: 'Invoice A'),
    new CreateInvoiceDTO(amount: 2000, currency: 'SAR', description: 'Invoice B'),
    new CreateInvoiceDTO(amount: 3500, currency: 'SAR', description: 'Invoice C'),
]);

Cancel an Invoice

$invoice = $moyasar->invoice()->cancel('invoice_12345');
// $invoice->status === 'canceled'

InvoiceDTO Reference

Property	Type	Notes
id	string	Unique identifier
status	string	initiated, pending, paid, expired, canceled
amount	int	Smallest currency unit
currency	string	ISO 4217
description	string
url	string	Hosted payment page — redirect customers here
amountFormat	string	e.g. "25.00 SAR"
logoUrl	string	Your merchant logo
callbackUrl	?string
successUrl	?string
backUrl	?string
expiredAt	?string
createdAt	string
updatedAt	string
metadata	array
payments	array	Payment attempts linked to this invoice

Need the raw Saloon response? It's always available:

$invoice  = $moyasar->invoice()->get('invoice_12345');
$response = $invoice->getResponse();
 
$response->status();   // 200
$response->headers();  // All response headers
$response->body();     // Raw JSON string

---

Payments

Invoices are great when you want Moyasar to host the checkout. Payments are for when you want full control — your own card form, your own UX, direct charges against a card or token.

Note

If you're collecting card details directly, make sure your integration is PCI-compliant. For most merchants, tokenization (using a saved token source) is safer and simpler than passing raw card numbers.

Create a Payment

use HamodaDev\Moyasar\Payment\DTO\CreatePaymentDTO;
use HamodaDev\Moyasar\Payment\DTO\Source\CreditCardSourceDTO;
 
$payment = $moyasar->payment()->create(new CreatePaymentDTO(
    amount:      10000,               // 100.00 SAR
    currency:    'SAR',
    description: 'Kindle Paperwhite',
    source: new CreditCardSourceDTO(
        name:                'John Doe',
        number:              '4111111111111111',
        month:               12,
        year:                2030,
        cvc:                 123,
        statementDescriptor: 'Century Store',
        threeDs:             true,
        manual:              false,
        saveCard:            false,
    ),
    callbackUrl: 'https://example.com/checkout/return',
    metadata:    ['cart_id' => 'cart_abc', 'customer_id' => '23432'],
    givenId:     'a1168bd1-47a4-4b97-8a50-dd5caaccacf2',
    applyCoupon: true,
));
 
echo $payment->status;  // "initiated", "paid", "authorized", ...
echo $payment->id;      // Store this with your order

About 3D Secure: when threeDs: true, the response may include a redirect URL the customer must visit to complete verification. Always check $payment->status and any redirect instructions returned by the API before assuming the payment succeeded.

About manual capture: setting manual: true authorizes the charge without capturing funds. Use this when you want to verify a payment now but only capture later (e.g. when you ship the item). See Capture below.

Supported Source Types

Source	DTO	Use case
Credit/debit card	CreditCardSourceDTO	Direct card charge
Apple Pay	Pass a raw array as source	Apple Pay token from the browser/app
STC Pay	Pass a raw array as source	STC Pay flow
Saved token	CreditCardSourceDTO with token set	Charging a previously saved card

Fetch a Payment

$payment = $moyasar->payment()->get('payment_12345');
 
if ($payment->status === 'paid') {
    // Mark the order as paid
}

List Payments

Same paginator API as invoices:

$paginator = $moyasar->payment()->list()->paginate($moyasar);
 
while ($paginator->hasMorePages()) {
    foreach ($paginator->items() as $payment) {
        echo "{$payment->id} — {$payment->status} — {$payment->amountFormat}\n";
    }
 
    $paginator = $paginator->nextPage();
}

Update a Payment

Update description or metadata after the fact — handy for enriching records once your internal workflow catches up:

use HamodaDev\Moyasar\Payment\DTO\UpdatePaymentDTO;
 
$moyasar->payment()->update('payment_12345', new UpdatePaymentDTO(
    description: 'Kindle Paperwhite — refurbished',
    metadata: [
        'cart_id'        => 'cart_abc',
        'customer_email' => 'john@example.com',
    ],
));

Refund a Payment

Full refund:

$payment = $moyasar->payment()->refund('payment_12345');

Partial refund (amount in smallest currency unit):

$payment = $moyasar->payment()->refund('payment_12345', amount: 2500);  // Refund 25.00 SAR

Capture an Authorized Payment

If you created the payment with manual: true, capture it when you're ready to actually charge the customer:

// Full capture
$payment = $moyasar->payment()->capture('payment_12345');
 
// Partial capture (e.g. only ship part of an order)
$payment = $moyasar->payment()->capture('payment_12345', amount: 5000);

Void a Payment

Cancel a payment before the funds settle in your bank account. Works on paid, authorized, or captured payments — as long as settlement hasn't happened yet.

$payment = $moyasar->payment()->void('payment_12345');
// $payment->status === 'voided'

Tip

Void vs. refund: void prevents the money from leaving the customer's account; refund returns money that's already moved. Void is cheaper and faster — always prefer it when available.

Payment Status Reference

Status	What it means
initiated	Payment created, customer hasn't paid yet
paid	Payment succeeded — you can fulfill the order
failed	Payment failed — check message on the DTO for the reason
authorized	Card authorized but not charged — needs capture()
captured	Authorized payment has been successfully captured
refunded	Payment refunded (full or partial)
voided	Payment canceled before settlement
verified	Card verified during tokenization (no charge made)

---

Error Handling

Saloon throws RequestException on any non-2xx response. The response object is attached, so you get full context:

use Saloon\Exceptions\Request\RequestException;
use Saloon\Exceptions\Request\FatalRequestException;
 
try {
    $payment = $moyasar->payment()->get('invalid_id');
} catch (RequestException $e) {
    $status = $e->getResponse()->status();
    $body   = $e->getResponse()->json();
 
    // Moyasar returns structured errors
    $type    = $body['type']    ?? null;  // e.g. "invalid_request_error"
    $message = $body['message'] ?? null;  // Human-readable summary
    $errors  = $body['errors']  ?? [];    // Field-level validation errors
 
    report($e);
} catch (FatalRequestException $e) {
    // Network failure — didn't even reach Moyasar
    report($e);
}

Moyasar Error Types

Type	Meaning	What to do
invalid_request_error	You sent bad parameters	Check the errors field, fix, retry
authentication_error	Invalid API key	Verify your secret key and base URL
rate_limit_error	Too many requests	Back off and retry with exponential delay
api_connection_error	Couldn't reach Moyasar	Retry with backoff
account_inactive_error	Account not activated for live payments	Contact Moyasar sales
3ds_auth_error	3D Secure failed	Ask the customer to try again
api_error	Something else went wrong	Retry; contact support if it persists

HTTP Status Codes

Code	Meaning
200	Success
400	Bad request — missing or invalid parameters
401	Unauthorized — API key invalid
403	Forbidden — credentials lack permission
404	Resource not found
405	Method not allowed — account not activated for live
429	Rate limited
500 / 503	Moyasar server issue — retry later

Warning

Moyasar occasionally returns 201 with a failure payload (e.g. bank declines). Don't trust the status code alone — always inspect $payment->status or $invoice->status on the DTO.

---

Testing Your Integration

Use Moyasar's test cards with your sk_test_... key. A few quick patterns:

Scenario	Card number
Successful charge	4111 1111 1111 1111
Declined charge	4000 0000 0000 0002
3D Secure required	4000 0000 0000 3220

Always verify your webhook handler works end-to-end in test mode before flipping to live.

---

Contributing

Bug reports and pull requests welcome. If you're adding a new Moyasar endpoint, please follow the existing Resource / Request / DTO pattern — consistency is why this SDK is pleasant to use.

License

Moyasar PHP is open-sourced software licensed under the MIT license.