Sign in
Checkout/Payment Links

Create Payment Link

Create a new checkout/payment link for collecting payments.

  • One-time products: Creates an invoice (with its associated payment) when paid.
  • Recurring products: Creates a subscription (with its associated invoice and payment) when paid.

Notes:

  • Cannot mix one-time and recurring products in the same payment link.
  • Installments are automatically disabled for recurring products (subscriptions).
  • Invoices, subscriptions and payments are created only after a successful payment.
post/api/v2/payment_links

Request body

namestring required

Name of the payment link

descriptionstring nullable

Optional description of the payment link

currency'SAR' | 'USD' | 'EUR' | 'GBP' | 'AED' | 'BHD' | 'KWD' | 'OMR' | 'QAR'

ISO 4217 currency codes supported by Moyasar.

Includes all currencies supported by Moyasar payment gateway.

couponsstring[]

List of coupon UUIDs to apply at the payment link level for discounts

max_number_of_paymentsinteger nullable

Maximum number of times this payment link can be used. If null or 0, the payment link can be used unlimited times; 0 is normalized to null. If organization_consumer_id is set, this number becomes how many times that specific customer can pay. Typically this should be set to 1 in that scenario.

valid_untilstring date-time nullable

Datetime after which the payment link is no longer valid. If no timezone is specified, UTC is assumed.

created_resource_effective_atstring date-time nullable

Datetime when the resource created from this payment link becomes effective. It is used as the one-off payment's scheduled_on, the recurring subscription's period_start, or the metered subscription's starts_at. If no timezone is specified, UTC is assumed.

confirmation_messagestring nullable

Optional message to display to the payer after successful payment

trial_period_daysinteger nullable

Free trial duration (in days) for subscriptions created from this link. Only valid when the link contains recurring (subscription) products. Must be between 1 and 365. Omit (or null) for no trial.

custom_fieldsobject nullable

JSON Schema (https://json-schema.org/specification) to define and validate fields collected from payers during payment. Only string type properties allowed.

success_redirect_urlstring uri nullable

URL to redirect the payer to after a successful payment

failure_redirect_urlstring uri nullable

URL to redirect the payer to after a failed payment

organization_consumer_idstring uuid nullable

ID of an existing consumer who will pay using this payment link. If set, customer information is not collected and this payment will be for that customer only. This is typically used when a specific customer is paying once. If not set, the link will collect customer information first. Use this when you expect multiple payments from different people, such as for a group trip or event.

custom_metadataobject nullable

Optional key-value metadata dictionary for attaching custom information. This metadata will be included as-is in payment link responses and webhook payloads.

contact_information_type'PHONE' | 'EMAIL'
document_idsstring[]

IDs of documents (previously uploaded via POST /v2/payment_links/documents) to attach to this payment link.

form_idstring uuid nullable

ID of a form to attach. Only one form can be attached per payment link.

Example request

{
  "custom_fields": {
    "properties": {
      "child_name": {
        "title": "Child Name",
        "type": "string"
      },
      "parent_email": {
        "title": "Parent Email",
        "type": "string"
      }
    },
    "required": [
      "child_name"
    ],
    "type": "object"
  }
}

Response

Successful Response

created_atstring date-time

Creation timestamp of the object.

updated_atstring date-time nullable

Last modification timestamp of the object.

idstring uuid4

Unique identifier (UUID) of the payment link

namestring

Name of the payment link

descriptionstring nullable

Description of the payment link

amountstring

Total payment link amount after discounts

original_amountstring

Original payment link amount before discounts

item_level_discounted_amountstring

Total amount discounted at the item level

currency'SAR' | 'USD' | 'EUR' | 'GBP' | 'AED' | 'BHD' | 'KWD' | 'OMR' | 'QAR'

ISO 4217 currency codes supported by Moyasar.

Includes all currencies supported by Moyasar payment gateway.

home_currency_amountstring nullable

Amount in home currency (SAR) at creation; for SAR links or when converted from other currencies.

exchange_rate_at_creationstring nullable

Exchange rate from link currency to home currency (SAR) at creation time

max_number_of_paymentsinteger nullable

Maximum number of times this payment link can be used

valid_untilstring date-time nullable

UTC datetime after which the payment link is no longer valid

created_resource_effective_atstring date-time nullable

UTC datetime when the resource created from this payment link becomes effective

confirmation_messagestring nullable

Message to display to the payer after successful payment

recurring_interval'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR'
recurring_interval_countinteger nullable

Number of intervals per billing cycle for recurring payments

trial_period_daysinteger nullable

Free trial duration (in days) for subscriptions created from this link. Only meaningful for recurring (subscription) products. When set, each consumer who subscribes via this link gets a free trial of this length, after which the first real billing period begins. Must be between 1 and 365.

status'INACTIVE' | 'ACTIVE' | 'COMPLETED'
organization_idstring uuid4

Unique identifier (UUID) of the organization

user_idstring uuid4

Unique identifier (UUID) of the user who created the payment link

organization_consumer_idstring uuid4 nullable

Unique identifier (UUID) of the organization consumer if linked to a specific consumer

deactivate_messagestring nullable

Message to display when the payment link is deactivated

custom_fieldsobject nullable

Custom fields schema for collecting additional information

success_redirect_urlstring nullable

URL to redirect the payer to after a successful payment

failure_redirect_urlstring nullable

URL to redirect the payer to after a failed payment

custom_metadataobject nullable

The key-value metadata dictionary passed during creation.

contact_information_type'PHONE' | 'EMAIL'
urlstring

Public URL of the payment link for sharing with payers

amount_collectedstring

Total amount collected from payments

amount_in_smallest_unitinteger

Payment link amount in smallest currency unit (e.g. halala for SAR).

original_amount_in_smallest_unitinteger

Original payment link amount (before discounts) in smallest currency unit.

amount_collected_in_smallest_unitinteger

Total amount collected in smallest currency unit.

Example response

{
  "custom_fields": {
    "properties": {
      "child_name": {
        "title": "Child Name",
        "type": "string"
      },
      "parent_email": {
        "title": "Parent Email",
        "type": "string"
      }
    },
    "required": [
      "child_name"
    ],
    "type": "object"
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.