PayTabs Support Portal

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 []
  • Card Discounts [ Discounts Cards ]
  • Card Discounts [ Discounts Amount ]
  • Card Discounts [ Discounts Percent ]
  • Card Discounts [ Discounts Title ]
• Usage Workflow
  • Sample Request Payload
  • Sample Response Payload
  • Sample IPN/Callback Response Payload (After Payment)
• The Expected Parameter Behaviors
  • Passing both discount_percent and discount_amount in the same transaction request.

Specifications 

• Card Discounts []
  

  The Parameter Tag/Name	card_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 Type	Array 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/Name	card_discounts[]. discount_cards
  JSON Example	{ "card_discounts":[ { "discount_cards ": "41111, 42222", ..... } } Generic
  Data Type	STRING
  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 Length	255 Character

  
  
  
  

• Card Discounts [ Discounts Amount ]
  
  

  The Parameter Tag/Name	card_discounts[].discount_amount
  JSON Example	{ "card_discounts":[ { "discount_amount": "30.00", ....... } } Generic
  Data Type	DECIMAL
  Required	❌  (Required only within card_discounts object if the discount_percent not present )
  Validation Rules	Can't be empty. Accept only digits
  Min Length	0.01
  Max Length	9999999999.99

  
  

  
  

• Card Discounts [ Discounts Percent ]

  
  

  The Parameter Tag/Name	card_discounts[].discount_percent
  JSON Example	{ "card_discounts":[ { "discount_percent" : "25", ..... } } Generic
  Data Type	STRING
  Required	❌  (Required only within card_discounts object if the discount_amount not present )
  Validation Rules	Can't be empty or zero
  Max Length	0.01
  Min Length	100

  
  

  
  

• Card Discounts [ Discounts Title ]

  
  

  The Parameter Tag/Name	card_discounts[]. discount_title
  JSON Example	{ "card_discounts":[ { "discount_title": "30 SAR discount on cards starts with 41111", ..... } } Generic
  Data Type	STRING
  Required	❌  (Required only within card_discounts object)
  Validation Rules	Can't be empty.
  Max Length	255 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"
	}
]
}

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

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

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