Coupons

Moyasar provides a powerful feature for merchants to offer discounts through Coupons. This allows merchants to define specific rules for coupon eligibility, which are then automatically checked during the payment process. If a coupon is applicable, it will be applied to the payment, reducing the total amount according to the discount defined by the merchant.

The following section outlines how to set up and apply coupons using the Moyasar API, including the required parameters and a step-by-step guide on how the coupon is processed.

Creating a Coupon

Merchants cannot create coupons directly by themselves. Instead, they must provide the following information to Moyasar, who will handle the coupon creation process:

Name: A human-readable name to identify the coupon.
Code: A machine-readable identifier for the coupon, for example, RAJHI15. This code is for reference only and is not used by customers to apply the coupon.
Discount Percentage: A value from 1% to 100% indicating the discount to be applied.
Max Discount: The cap for the discount, for example, 50 SAR.
Start Day: The start date for when the coupon becomes valid.
End Day: The end date for when the coupon expires.
BIN List: A list of BINs (Bank Identification Numbers) that the coupon applies to.
- Note: Physical card and Apple Pay BINs are different, so you’ll need to get both from your card issuer.

How Coupons Are Applied

Let’s suppose you have a coupon with the following details:

Coupon Name: RAJHI15
Discount Percentage: 15%
Max Discount: 150 SAR
Applicable BIN List: 48478312, 50696822

Please note that the coupon will only be applied if the current date falls within the valid range (between the Start Day and End Day) set for the coupon. For the sake of this example, we will not mention the Start Day and End Day, but they are taken into account when applying the coupon.

If a payment matches the coupon criteria, such as having a valid BIN and being within the applicable date range, the coupon will be applied, and the payment amount will be reduced based on the defined discount.

Now, let’s suppose you make a payment using a credit card or Apple Pay with a card BIN starting with 48478312. If this BIN is on the coupon's applicable list, the coupon will be applied.

In this case, the payment amount was 2000.00 SAR. When the coupon is applied, 300.00 SAR is deducted from the full amount, but only 150.00 SAR is actually deducted because the coupon has a maximum discount cap of 150.00 SAR.

The payment response metadata would look like this:

{
  "#coupon_id": "7848a897-10e7-4977-b719-81884d4cc999",
  "#coupon_code": "RAJHI15",
  "#coupon_discount": 15,
  "#coupon_original_amount": 200000,
  "#coupon_max_discount_amount": 15000
}

Important

When the merchant receives the payment response, they must check whether a coupon has been applied and update the order in their system accordingly. Failing to do so will result in inconsistencies in their records and the payment gateway.

BIN Ranges

Please note that each source has a different BIN range for the same card product, for example, the same exact mada card from a local Saudi issuer has the BIN ranges for:

Card: 48478312
Apple Pay: 50696822

Coupon Flow

Disable Coupon Per Payment

Moyasar enables merchants to have control whether a coupon should get applied or not per payment. For example, a merchant may want to limit coupon application per user per campaign. For more details, check the Create Payment API.

Checking Available Coupons

Before creating a payment, you can check whether a coupon will apply for a given card or wallet token by calling the Available Coupon endpoint. This is useful when you want to display a discount preview in your checkout UI (e.g. "You'll save 15% with this card") before the customer completes the payment.

Endpoint

POST /v1/payments/available_coupon

Authenticated with your publishable or secret API key, the same as other Moyasar API endpoints.

Request Parameters

Parameter	Type	Required	Description
`type`	string	Yes	The payment source type. One of: `creditcard`, `applepay`, `googlepay`, `samsungpay`.
`number`	string	Required when `type` is `creditcard` and `token` is not provided	The card number. Only the BIN is used to evaluate the coupon — the full number is never stored.
`token`	string	Required when `number` is not provided	A saved card token. The BIN associated with the token is used to evaluate the coupon.

Response

If a matching coupon is found, the endpoint returns the coupon object:

{
  "id": "7848a897-10e7-4977-b719-81884d4cc999",
  "name": "Rajhi Card 15%",
  "code": "RAJHI15",
  "discount": 15,
  "max_discount_amount": 15000,
  "start_date": "2026-01-01T00:00:00.000Z",
  "end_date": "2026-12-31T23:59:59.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "disabled_at": null,
  "active": true,
  "criteria": {}
}

If no coupon matches the provided card or token, the endpoint returns null with HTTP 200 OK.

Field	Type	Description
`id`	string	Unique identifier of the coupon.
`name`	string	Human-readable name of the coupon.
`code`	string	Internal coupon code, e.g. `RAJHI15`. Reference-only, not entered by customers.
`discount`	integer	Discount percentage (`1`–`100`).
`max_discount_amount`	integer	Maximum discount cap, in the smallest currency unit (e.g. halalas).
`start_date`	string	ISO-8601 timestamp from which the coupon becomes valid.
`end_date`	string	ISO-8601 timestamp at which the coupon expires.
`disabled_at`	string	ISO-8601 timestamp the coupon was disabled, or `null` if still enabled.
`active`	boolean	`true` if the coupon is currently active (not disabled and within its validity range).
`criteria`	object	The matching criteria used by the coupon (e.g. applicable BIN list).

Example Request

Using a card number:

curl https://api.moyasar.com/v1/payments/available_coupon \
  -u sk_test_xxxx: \
  -d "type=creditcard" \
  -d "number=4847831234567890"

Using a saved card token:

curl https://api.moyasar.com/v1/payments/available_coupon \
  -u sk_test_xxxx: \
  -d "type=creditcard" \
  -d "token=tok_xxxx"

For Apple Pay, Google Pay, or Samsung Pay, pass the corresponding type along with the source token.

Typical Use Cases

Display a discount badge or "You'll save X%" message in your checkout UI before the customer pays.
Conditionally show or hide promotional content based on coupon eligibility.
Pre-validate that a coupon will apply, so the customer is not surprised when the final payment is reduced.

note

This endpoint only returns whether a coupon is available for a given card or token — it does not apply the coupon. The coupon is automatically applied during the Create Payment call when the criteria match. See How Coupons Are Applied above.

Creating a Coupon​

How Coupons Are Applied​

BIN Ranges​

Coupon Flow​

Disable Coupon Per Payment​

Checking Available Coupons​

Endpoint​

Request Parameters​

Response​

Example Request​

Typical Use Cases​