Skip to main content

Request: Pre-transaction card approval (card_approval)

Warning

This parameter ONLY working with those integration types (HPP, Invoice via Payment Endpoint, Managed Form, and Own Form).

The Pre-transaction card approval card_approval is a powerful feature offered by PayTabs that enables merchants to implement custom validation logic based on the Bank Identification Number (BIN) of a customer's payment card. This feature empowers businesses to enforce custom approval logic before a transaction is authorized, based on the characteristics of the customer’s payment card.

Upon initiation of a payment, PayTabs transmits a structured request to the merchant’s designated validation endpoint, containing essential card metadata such as the first and last digits of the card, expiry date, and a unique card hash. The merchant’s system is expected to respond within a strict 2-second window, indicating whether the transaction should proceed or be declined. This process ensures that payment decisions are aligned with the merchant’s internal business rules, risk policies, and promotional strategies.

By implementing the card_approval using supported manuals in a manner that will be explained later, merchants can implement real-time, card-specific transaction validation.

How this parameter could benefit you?​

Here are some scenarios to help you understand when to use the card_approval object feature:

  • Controlled Discount Eligibility: Merchants can prevent customers from repeatedly availing promotional discounts using the same card by validating the card BIN or hash. This ensures fair usage of offers and protects promotional budgets.

  • Mitigation of Price Speculation: For businesses operating in sectors with price-sensitive products—such as gold or other commodities—this feature mitigates speculative behavior by preventing customers from securing outdated prices at checkout or the payment page. It ensures that transactions reflect real-time market values, thereby preserving pricing integrity.

  • Dynamic Pricing Control: For businesses with frequently changing prices (e.g., travel, e-commerce, or commodities), this feature helps prevent speculative behavior. Customers cannot lock in a discounted price using a card that is not eligible or by exploiting timing gaps.

  • Personalized Customer Experience: Businesses can offer tailored discounts or benefits based on the card type (e.g., premium, rewards, debit), improving customer satisfaction and loyalty.

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

  • E-Commerce & Retail: Prevents misuse of promotional codes, and enables targeted discounts for specific cardholders (e.g., premium credit cards).

  • Travel & Hospitality: Helps manage dynamic pricing for flights, hotels, and packages. Also prevents speculative bookings using ineligible cards.

  • Subscription-Based Services: Ensures that recurring discounts or trials are not abused using the same card.

  • Online Marketplaces: Allows sellers to define their own BIN-based rules for accepting payments.

  • Telecommunications: Offers device or plan discounts based on card type or issuing bank.

  • Event Ticketing: Prevents scalping or speculative purchases by validating card eligibility in real-time.


Limitations​

While the card_approval object offers several benefits, there are some limitations to consider:

  • Dependency on Real-Time Response: The system requires a response within 2 seconds. If the merchant’s server is slow, under heavy load, or experiences downtime, transactions may be automatically rejected (if block_if_no_response is set to true), hence be caution while using the parameter block_if_no_response.


How to Use?​

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

  • Within the initiation of the request payload of the payment in Step 3 via any of the supported integration types by this object, you will use the optional object card_approval within the main request payload itself as shown below:

    {
        ...
        "card_approval": {
            "validation_url": "https://compnay-domain.com/card-approval",
            "bin_length": 8,
            "block_if_no_response": true
        },
        ....
    }

  • Once you post your request, you will receive a redirect_url that you will need to direct the customer to complete the payment process (HPP, and invoice via Payment Endpoint):

    {
       ...
       "redirect_url": "https://secure.paytabs.com/payment/page/599458B*************B4818688",
       ....
    }

    Or direct payment via Managed or Own forms.

  • Upon the customer’s confirmation of payment, the system will trigger a card approval request to the specified validation endpoint, enabling the merchant to validate the transaction based on the card’s BIN and associated business rules.

  • Finally, Some transactions type are direct transactions that don't need any further payment process and other will need to you to redirect the customer to a page for either authenticate the cardholder via the 3D Secure or processed with asking to fill the bank card details within the payment page. You may need to check his customer experience after in the coming Expected Payment Flow Behavior.



Parameter Specifications​

  • card_approval

    Parameter
    card_approval
    DescriptionIndicates the merchant's ability to verify the customer's card BIN before proceeding with the transaction.
    Data TypeOBJECT
    Required✘
    Sample
    "card_approval": {
       "validation_url": "https://domain.com/card-approval",
       "bin_length": 5,
       "block_if_no_response": false
    }
    card_approval's Nested Parameters
    Nested ParameterData TypeMinMaxRequired
    validation_url
    		STRINGN/A255 Characters (Valid URL)✔
    The provided endpoint URL where PayTabs notifies your system of customer card details for validation before proceeding with the payment transaction
    bin_length
    		INT68✔
    Indicates the length of the Bank Identification Number (BIN) segment from the left side of the customer's card number.
    block_if_no_response
    		BOOLEANN/AN/A✔
    Specifies the action to be taken in the event of no response or a timeout from the endpoint—either to fail the transaction or proceed with processing.



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.

{
    "profile_id": "987###",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_currency": "SAR",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",

    "card_approval": {
        "validation_url": "https://compnay-domain.com/card-approval",
        "bin_length": 8,
        "block_if_no_response": true
    },

    "customer_details": {
        "name": "Demo Account",
        "email": "[email protected]",
        "phone": "+966 0000000000",
        "street1": "address street",
        "city": "city",
        "state": "state",
        "country": "SA",
        "zip": "45555",
        "ip": "1.1.1.1"
    },
    "payment_token": "xxxxxxxxxxxx"

}

Expected Payment Flow Behavior​

  1. You will initiate a payment request using the guide mentioned [here]

  2. You will use the card_approval object according to the above Specifications

  3. Then you will receive the response payload containing the redirect_url meaning you have initiated a correct payment request.
    {
        .
        "redirect_url": "https://secure.paytabs.com/payment/page/52E5B6B*************B48688",
        .
    }

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

  5. After this, your customer would proceed normally with payment by choosing the preferred payment method (if available), and providing his card information.
    Payment Page

  6. Once the customer press the Pay Now button, and before proceed with the next step. you will receive a request with the customer card details to validate:
    {
        "transaction_reference": "TST2517502099370",
        "card_first_digits": "41111111",
        "card_last_digits": "1111",
        "card_expiry_year": 2029,
        "card_expiry_month": 12,
        "cart_id": "CART#1001",
        "customer_reference": "customer_ref-1",
        "language": "en-GB",
        "card_hash": "HfaJt+c4SGp+2L1aBu7IxGgaEdUyX5Uz3LgiF8YH6RA=",
        "signature": "5a6d9df57c53c8eee8b16a57b627b89ef212420d9df993616e1585aad6a241d2"
    }

  7. If the customer's card details are approved, and the card supports 3D Secure (3DS), you will receive a redirect_url directing the customer to their issuing bank’s 3DS authentication page, where they will be prompted to enter a One-Time Password (OTP) to complete the transaction.

  8. Or if you reject the customer's card a declined transaction will be created 354 - Card not approved by merchant:

    single framed view

  9. Finally, the customer 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.