Skip to main content

Request/Response: Donation Mode (donation, cart_min, cart_max)

Warning

This parameter ONLY working with those integration types (Hosted Payment Page, and PayLinks).

In the evolving landscape of online payments, flexibility and user-centric options are paramount. PayTabs introduces the Donation Mode feature, designed to enhance the donation experience for users. This feature allows merchants to create a payment page where donors can select an amount within a predefined range, offering a seamless and customizable donation process.

Instead of a fixed payment page with a predefined amount, this 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).

By understanding the key parameters such as donation_mode, cart_min, and cart_max, businesses can effectively integrate this feature to cater to their audience’s needs and preferences.

How this parameter could benefit you?​

Implementing the donation_mode parameter can thus provide a more tailored and efficient payment experience, benefiting both your business operations and customer satisfaction.

  • Enhanced Flexibility: You can set a range for payments, allowing customers to choose an amount that suits their budget. This flexibility can increase customer satisfaction and potentially boost sales.

  • Improved Cash Flow Management: By allowing partial payments or deposits, you can manage your cash flow more effectively. This is particularly useful for high-value transactions where customers might prefer to pay in installments.

  • Increased Customer Engagement: Offering a customizable payment option can make your services more attractive to a broader audience. Customers appreciate having control over how much they pay within a given range.

  • Simplified Payment Process: The predefined range simplifies the payment process for both you and your customers, reducing the likelihood of errors and ensuring smoother transactions.

  • Versatility Across Industries: Whether you’re in hospitality, event management, education, or any other sector, this feature can be adapted to fit various payment scenarios, making it a versatile tool for your business.

  • Encourages Larger Payments: By setting a minimum and maximum range, you can subtly encourage customers to pay more than the minimum, potentially increasing your revenue.

Name but a few different Businesses/Industries that can benefit from this API parameter:

  • Non-Profits and Charities: Enables a seamless donation process, encouraging more contributions.

  • Crowdfunding Platforms: Allows backers to choose their contribution amount, enhancing user satisfaction.

  • Educational Institutions: Facilitates fundraising campaigns by allowing alumni and supporters to donate varying amounts.

  • Hotel Reservations: As mentioned, hotels can use this feature to allow customers to pay an amount within a specified range based on their reservations. This can be particularly useful for deposits or partial payments.

  • Event Ticketing: Event organizers can use this mode to let attendees choose their ticket price within a range, accommodating different budget levels and encouraging more participation.

  • Membership Fees: Clubs or organizations can offer flexible membership fees, allowing members to pay an amount they are comfortable with within a set range.

  • Crowdfunding: Similar to donations, crowdfunding campaigns can benefit from this feature by allowing contributors to select their contribution amount within a predefined range.

  • Educational Institutions: Schools and universities can use this for flexible tuition payments, where students or parents can pay an amount within a specified range based on their financial situation.

  • Service Payments: Freelancers or service providers can use this feature to let clients pay within a range for services rendered, providing flexibility and accommodating different client budgets.

Limitations​


  • Payments Method Compatibility: This feature is compatible ONLY with any cards payment methods. Such as Visa, MasterCard, Amex, Mada, Meeza Debit card, .. and so.

How to Use?​

In order for you to start use the donation_mode feature, you kindly need to follow the below simple steps:

  • Within the initiation the request payload of the payment page/link in Step 3 via any of the supported integration types by this feature, you will use the optional parameters donation_mode within the main request payload itself.

  • Along with this optional parameter (object) donation_mode, you must pass both of the following optional parameters (objects) as clarified in the below sample:

    be aware of
    Both cart_min and cart_max MUST be passed together along with a true as a value of the donation_mode parameter. Otherwise, you will face validation errors/response.
    {
        .
        .
        "donation_mode":true,
        "cart_min":5,
        "cart_max":500
        .
        .
    }

  • Once you post your request, you will receive a response that includes either a redirect URL, or a link URL (depending on the integration type used).

    "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",
    "link_url": "https://secure.paytabs.com/payment/link/109430/1474XX7",

  • Finally you will need navigate/redirect your customer to the the previous mentioned link as this is crucial for your customer to proceed through the payment process. You may need to check his customer experience after in the coming Expected Payment Flow Behavior.

Parameter Specifications​

  • donation_mode

    Parameter
    donation_mode
    DescriptionThis parameter will define whether this payment has a predefined amount or the customer will be entering the amount based on the passed cart_min and cart_max.
    Data TypeBOOLEAN
    Required✘
    Sample
    {
        "donation_mode ":true
    }
  • cart_min

    Parameter
    cart_min
    DescriptionThis parameter is required only if donation_mode property is present to represent the minimum amount that the customer can enter
    Data TypeDECIMAL
    Required✘
    Min0.01
    Max9999999999.99
    Sample
    {
        "cart_min":5
    }
  • cart_max

    Parameter
    cart_max
    DescriptionThis parameter is required only if donation_mode property is present to represent the maximum amount that the customer can enter.
    Data TypeDECIMAL
    Required✘
    Min0.01
    Max9999999999.99
    Sample
    {
        "cart_max":500
    }

Request & Response Payloads Samples​

The below sample request payload will show you how you can pass the above-mentioned required parameter/s, which are needed to be passed with valid values to perform a request. Along with the response payload received after using this request payload.

be aware of
Both cart_min and cart_max MUST be passed together along with a true as a value of the donation_mode parameter. Otherwise, you will face validation errors/response.
{
    "profile_id": 9*****4,
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_description": "Description of the items/services",
    "cart_id": "CART#1001",
    "cart_currency": "SAR",
    "customer_details": {
        "name": "Technical Support",
        "email": "[email protected]",
        "phone": "+966 55 xxxxxx6",
        "street1": "address street",
        "city": "Jeddah",
        "state": "Jeddah",
        "country": "SA",
        "zip": "22230"
    },
    "shipping_details": {
        "name": "Technical Support",
        "email": "[email protected]",
        "phone": "+966 55 xxxxxx6",
        "street1": "address street",
        "city": "Jeddah",
        "state": "Jeddah",
        "country": "SA",
        "zip": "22230"
    }
    "donation_mode":true,
    "cart_min":5,
    "cart_max":500
}

Expected Payment Flow Behavior​

  1. As mentioned above in the How to use? section, As a merchant you would initiate a payment request per the above Specifications, same as the sample codes mentioned in the samples section above.

  2. Then, you will receive a response that includes redirect URL. This means you have initiated a correct payment request/page successfully.

    "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",

  3. Next, you should redirect your customer to this URL so the payment process can be finalized.

  4. After this, your customer would proceed normally with payment by providing his card information, and the payment amount as long as it's within the predefined range.

    transaction view

  5. Then, he will be redirected to his issuer bank 3DS/OTP page to authenticate the used card

  6. Finally, he would be redirect to a success/error page accordingly. By this time, you will be able to see his transaction on your merchant dashboard, whether it's accepted/authorized or not.transaction view

    transaction view

We are glad to be always in help. We aim to serve you better each time. As such, please spare a minute to share feedback about your recent experience with PayTabs Developers , on Trustpilot, or Google Reviews.