Skip to main content

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 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
}


:::warning[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

```mermaid
sequenceDiagram
    Merchant->>Moyasar API: Payment Request
    Moyasar API->>Moyasar API: Apply Coupon
    Moyasar API->>Merchant: Payment Response
    Merchant->>Merchant: Update Order with new Amount if coupon is applied