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. 

Payment Page with active donation mode enables you to create a PayPage that is based on not providing a fixed amount as a purchase. It will be a range between x (minimum) and y (maximum), which will give the client the ability to choose the amount to be paid (donate) from his side within this predefined x-y range (minimum-maximum amount range). You may have the same functionality available via How to manage PayLinks on PayTabs Dashboard? solution article. Also, this can be done via the normal "Hosted Payment Page".

This article is dedicated to the clarification of the donation mode (donation_mode) parameter. "donation_mode" is one of the mandatory parameters that the request should have. 

In this article, you will be going to know:

• Specifications 
  • Donation Mode
  • Cart Min
  • Cart Max
• Usage Workflow
  • Sample Request Payload
  • Sample Response Payload
• The Expected Parameter Behaviors
  • Passing donation properties along with cart_amount property

Specifications 

• Donation Mode

  The Parameter Tag/Name	donation_mode
  JSON Example	{ "donation_mode":true }
  Data Type	Boolean
  Required	❌
  Validation Rules	true or false

  
  
  

• Cart Min

  The Parameter Tag/Name	cart_min
  JSON Example	{ "cart_min":5 }
  Data Type	Decimal
  Required	❌ (Required only if donation_mode property is present)
  Validation Rules	Accept only digits and a decimal point. Not accept zero or empty value
  Max Length	9999999999.99
  Min Length	0.01

  
  
  
  

• Cart Max

  The Parameter Tag/Name	cart_max
  JSON Example	{ "cart_max":500 }
  Data Type	Decimal
  Required	❌ (Required only if donation_mode property is present)
  Validation Rules	Valid URL Recommended to pass it as an HTTPS URL, otherwise, will reflect on the response behavior
  Max Length	9999999999.99
  Min Length	0.01

  
  
  

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 "donation_mode" 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",

    "donation_mode":true,
    "cart_min":5,
    "cart_max":500
}

{
    "tran_ref": "TST2231101374414",
    "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://secure-egypt.paytabs.com/payment/page/599**ED7",
    "serviceId": 2,
    "profileId": 987654,
    "merchantId": 123456,
    "trace": "PMNT0404.6368BC3D.000BAF4C"
}

The Expected Parameter Behaviors

The Payment Page will display input or the customer to enter her/his donation amount, if the amount is not in the defend min and max, the transaction will not proceed.

The expected behaviors according to the passed value are:

• Passing donation properties along with cart_amount property

In this case, PayTabs will ignore the cart amount value and only accept input value between the donation min and max range.