Paytabs provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages. 




This article is dedicated to the clarification of the Card Discounts (card_discounts) parameter. "card_discounts" is one of the optional parameters that the request should have, which provides discounts for some of your valued customers via the property card_discounts, which contains an array of objects each object for a specific range of customers cards discounts.


In this article, you will be going to know:

Specifications 


  • Card Discounts []

    The Parameter Tag/Namecard_discounts
    JSON Example
    {    
"card_discounts":[
	{
	"discount_cards":"41111,520000",
	"discount_amount": "30.00",
	"discount_title": "30.00 SAR discount on cards starts with 41111, 520000"
	},
	{
		.....
	}
}
    Generic
    Data TypeArray of objects
    Required
    ❌
    Validation Rules
    • Must be an Array of objects.
    • The array can have one object or more.
    • Each object must have the properties discount_cards, discount_amount or discount_percent, and discount_title



  • Card Discounts [ Discounts Cards ]

    The Parameter Tag/Namecard_discounts[]. discount_cards 
    JSON Example
    {    
"card_discounts":[
	{
	"discount_cards ": "41111, 42222",
	.....
	}
}
    Generic
    Data TypeSTRING
    Required
      ❌  (Required only within card_discounts object)
    Validation Rules
    • Can't be empty.
    • Must provide a comma-separated list of card prefixes 
    • Each card discount cards prefix must be between 4 and 10 digits
    Max Length255 Character 




  • Card Discounts [ Discounts Amount ]

    The Parameter Tag/Namecard_discounts[].discount_amount 
    JSON Example
    {    
"card_discounts":[
	{
		"discount_amount": "30.00",
		.......
	}
}
    Generic
    Data TypeDECIMAL
    Required
      ❌  (Required only within card_discounts object if the discount_percent not present )
    Validation Rules
    • Can't be empty.
    • Accept only digits
    Min Length0.01 
    Max Length9999999999.99



  • Card Discounts [ Discounts Percent ]


    The Parameter Tag/Namecard_discounts[].discount_percent
    JSON Example
    {    
"card_discounts":[
	{
		"discount_percent" : "25",
		.....
	}
}
    Generic
    Data TypeSTRING
    Required
      ❌  (Required only within card_discounts object if the discount_amount not present )
    Validation Rules
    • Can't be empty or zero
    Max Length0.01 
    Min Length100



  • Card Discounts [ Discounts Title ]


    The Parameter Tag/Namecard_discounts[]. discount_title 
    JSON Example
    {    
"card_discounts":[
	{
	"discount_title": "30 SAR discount on cards starts with 41111",
	.....
	}
}
    Generic
    Data TypeSTRING
    Required
      ❌  (Required only within card_discounts object)
    Validation Rules
    • Can't be empty.
    Max Length255 Character 


Usage Workflow


Along with the required parameters mentioned in our Step 3 - PT2 API Endpoints | Initiating the payment solution article, you will need to set the "card_discounts" as shown below:

Sample Request Payload


{
"profile_id": "987654",
"tran_type": "sale",
"tran_class": "ecom",
"cart_id": "CART#1001",
"cart_currency": "USD",
"cart_amount": 500,
"cart_description": "Description of the items/services",
"card_discounts":[
	{
	"discount_cards" : "41111,520000",
	"discount_amount" : "30.00",
	"discount_title" : "30.00 SAR discount on cards starts with 41111, 520000"
	}
]
}
JavaScript



Sample Response Payload

  

{
"tran_ref": "TST2231301375864",
"tran_type": "Sale",
"cart_id": "CART#1001",
"cart_description": "Description of the items/services",
"cart_currency": "USD",
"cart_amount": "500.00",
"tran_currency": "",
"tran_total": "0",
"return": "none",
"redirect_url": "https://***.paytabs.com/payment/page/599**D7",
"serviceId": 2,
"profileId": 987654,
"merchantId": 123456,
"trace": "PMNT0404.6368BC3D.000BAF4C"
}
JavaScript



Sample IPN/Callback Response Payload (After Payment)

    

{
  "tran_ref": "TST2231501379251",
  "merchant_id": 123456,
  "profile_id": 987654,
  "cart_id": "CART#1001",
  "cart_description": "Description of the items/services",
  "cart_currency": "USD",
  "cart_amount": "500.00",
  "tran_currency": "USD",
  "tran_total": "470.00",
  "tran_type": "Sale",
  "tran_class": "ECom",
  "customer_details": {
    ....
  },
  "shipping_details": {
    ....
  },
  "payment_result": {
    "response_status": "A",
    "response_code": "G75022",
    "response_message": "Authorised",
    "cvv_result": " ",
    "avs_result": " ",
    "transaction_time": "2022-11-11T13:57:02Z"
  },
  "payment_info": {
    "payment_method": "Visa",
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111",
    "expiryMonth": 2,
    "expiryYear": 2028
  },
  "ipn_trace": "IPNS0003.636E54AF.00006A22"
}
JavaScript


Once the payment is completed by any of the cards eligible for the discount, you will receive in the Callback/IPN response the actual transaction amount after applying the discount in a paramter called tran_total (the actual amount deducted from the customer) along with the cart_amount are the requested amount.
	

	
 Also you will receive the card details which includes the used card prefixes in payment_info object in the Callback/IPN response and query transaction API response


The Expected Parameter Behaviors


After redirecting the customer to the payment page, PayTabs will compare the customer's card number if its eligible, then a discount will apply to the transaction amount as shown below:


The expected behaviors according to the passed value are:



  • Passing both discount_percent and discount_amount in the same transaction request.


    In this case, PayTabs will sum the total of both discounts percent/amount and apply it to the requested amount, as shown below: