Skip to main content

Creating invoices

Moyasar e-Invoices Overview​

Moyasar e-invoice is an additional service dedicated to providing online payment for websites and electronic systems with a structured and secure mechanism. This allows the merchants to create e-invoices through Moyasar’s dashboard or Moyasar’s API and to be sent or presented to customers manually or automatically.

Creating Invoice Via Moyasar’s Dashboard​

In the Dashboard, you can:

  • Create an invoice
  • Add/Edit Amount, Description, Expire Date, and Metadata to invoices

Click here for the steps to create an invoice through the Dashboard.

Creating Invoice Via Moyasar’s API​

Moyasar e-Invoices APIs enable merchants to generate invoices programmatically and integrate them with their online stores and backend systems.

Invoice LifeCycle​

Before Starting​

Before you start integrating with Moyasar API, make sure you complete these steps:

  1. Sign up for a Moyasar test account at
  2. Get Your API Keys to authenticate your requests

Step 1: Creating an invoice​

Start by sending a request to Moyasar invoices and create an endpoint to create an invoice in your server.

https://api.moyasar.com/v1/invoices

You will need to specify the following required data to be included in the request:

ParameterDescription
* amount (required)The amount should be in the smallest currency unit. Means, ( 100 Halals to charges 1 Riyal )
currency3-letter ISO code for currency. (default: SAR)
* description (required)An arbitrary string that you can attach to an invoice object. This may include a description of the merchandise or the service that your customer is billed for. The invoice description is displayed on the invoice alongside the amount when the invoice is presented to the user.
expired_atSpecifies when the invoice will get expired. An expired invoice cannot have payment attempts as its status will be expired.
success_urlAn endpoint on your site, that we will redirect to after the customer pays successfully.
back_urlAn endpoint on your site, that we will redirect to after the user clicks on the back button.
metadataSet of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
phoneA Saudi mobile number (for example 0500000000 or +966500000000) to send the invoice link to by SMS. See Send the link by SMS. Optional.

Invoice Notification

Invoices support asynchronous notification callback when the status changes from initiated to paid upon the customer's successful payment.

To enable notifications for an invoice, you’d provide:

ParameterDescription
callback_urlAn endpoint on your server, for receiving notifications about paid invoices. (e.g. https://yourdomain/some-endpoint)

For more technical details about Moyasar invoices API, please refer to ourAPI

Step 2: Share with the customer​

Then we will give you a link to the invoice on our website, you can send that link to the user or redirect him to the invoice page, then we will handle the payment form and validations.

Instead of sending the link yourself, you can have it sent to the customer by SMS when the invoice is created. Add the phone parameter with a Saudi mobile number to the create invoice request.

  • The phone field can only be used if you contacted Moyasar to set up your credentials. A request with phone fails if they are not configured.
  • The SMS is sent as part of the request. If it cannot be delivered, the invoice is not created and the request fails with the error SMS could not be delivered, followed by the reason (for example insufficient balance or an invalid sender name), so you can fix it and safely retry.
  • If the delivery status cannot be confirmed (for example the SMS provider does not answer in time), the invoice is kept and the error message contains its id. Check that invoice before retrying, to avoid creating a duplicate.
  • The message is written in the invoice language of your account (Arabic or English) and contains the invoice amount and link.
  • phone is only supported when creating a single invoice, not in bulk or when updating an invoice.