FAQ

Whitelabel API

1. How do I activate the Whitelabel API feature?

   • To activate the Whitelabel API feature, please contact your UPayments Account Manager.

2. What are the benefits of the Whitelabel API?

   • The Whitelabel feature allows merchants to display the payment gateway directly on their checkout page, eliminating the need to redirect users to the UPayments payment page.
   • UPayments V2 supports KNET, Credit Card, Apple Pay, Samsung Pay, and Google Pay with the Whitelabel feature.
   • For more details, refer to our Whitelabel & Non-whitelabel API page.

Non-whitelabel API

1. How can we fetch track_id for Non-whitelabel API?

   • In the Non-whitelabel API, the track_id can be retrieved from the webhook returnUrl or cancelUrl.
   • The track_id is generated only after the cardholder selects a payment gateway.

   ---

   
   

Multivendor API

1. How can sub-vendors receive deposits from transactions made on their platform?

   • In the Multi-Vendor feature, sub-vendors receive payments directly into their respective accounts.

2. Does the Multi-Vendor API support the KFAST feature for saving Debit card details?

   • Yes, all merchants utilizing UPayments can benefit from the KFAST & Save Card Feature. This can be enabled by configuring the respective parameters in the API.

3. How do I split a customer payment between multiple vendors with a commission and delivery fee?

   1. You can handle multi‑vendor payments using a single parent payment with an extraMerchantData array, which defines each vendor’s share and the admin’s commission.
      Steps to Calculate Commission and Delivery Fee Split:
      1. Calculate the total price of all vendor products.
      2. Determine the admin’s target earnings:
         adminTarget = (productsTotalPrice * commissionRate) + deliveryFee
      3. Compute the total customer payment:
         grossTotal = productsTotalPrice + deliveryFee
      4. Calculate the percentage to use for ccCharge and knetCharge:
         percentageAmount = (adminTarget / grossTotal) * 100
         Example Scenario:
   2. Two vendors, each selling items for 500 KWD
   3. Delivery fee: 200 KWD
   4. Commission: 10%
      productsTotalPrice = 1000
      adminTarget = (1000_0.1)+200 = 300
      grossTotal = 1200
      percentageAmount = 300/1200_100 = 25%
      
      
      Request Example:
      JSON

      {  
        "products": [  
          { "name": "Logitech K380", "price": 500, "quantity": 1 },  
          { "name": "Logitech M171 Wireless Optical Mouse", "price": 500, "quantity": 1 }  
        ],  
        "order": {  
          "id": "202210101255255144669",  
          "reference": "11111991",  
          "description": "Purchase order received for Logitech",  
          "currency": "KWD",  
          "amount": 1200  
        },  
        "extraMerchantData": [  
          {  
            "amount": 600,  
            "ccCharge": 25,  
            "ccChargeType": "percentage",  
            "knetCharge": 25,  
            "knetChargeType": "percentage",  
            "ibanNumber": "1111111111111111"  
          },  
          {  
            "amount": 600,  
            "ccCharge": 25,  
            "ccChargeType": "percentage",  
            "knetCharge": 25,  
            "knetChargeType": "percentage",  
            "ibanNumber": "2222222222222222"  
          }  
        ]  
      }
      

      Each vendor receives 450 KWD (500 − 10% commission).
      Admin earns 100 KWD commission + 200 KWD delivery fee = 300 KWD.

      📘

      Note:

      The sum of all extraMerchantData.amount must equal order.amount
      This method supports any number of vendors, variable prices, delivery fees, and commission rates. Save Cards, KFAST

4. What distinguishes the KFAST feature from the Save Cards feature?

   • The KFAST feature is specifically designed for KNET, allowing cardholders to securely save their KNET card details via tokenization for faster and more convenient future transactions.
   • The Save Card feature, on the other hand, allows customers to save their credit card details through tokenization. Refer to the Tokenization section for more details.

5. How do I configure payment methods for my sub-merchants?

   Payment methods are set at the main merchant account level and apply to all of your sub-merchants. You cannot customize payment methods for each sub-merchant individually.

   ---

   
   

Checking Payment Status

1. What is the payment response, and how can I get it?

   • Payment response fields are received in the success or cancel URL after payment, as well as via the webhook. Refer to our webhook documentation for more details on response fields.
   • Payment status and details can also be obtained using the Check Payment Status API.

2. Is there an endpoint to check whether a payment has been successfully captured or not?

   • The webhook can be used to verify if a payment has been successfully captured.
   • Alternatively, payment status and details can be obtained from the Check Payment Status API.

3. How can we get the payment ID, transaction ID, order ID, payment status, and time?

   • Payment ID, track ID, Order ID, payment status, and time can be retrieved from the webhook.
   • Payment status and details can also be obtained from the Check Payment Status API.
   • Successful transactions will redirect to the returnUrl. All other scenarios, such as failed or canceled payments, will redirect to the cancelUrl.

4. What is the recommended approach for implementing a payment inquiry?

   • The recommended approach for implementing a payment inquiry using the UPayments API involves:
     • Implementing the REST API with a notify URL.
     • Obtaining the payment URL.
     • Updating the transaction based on the response received on the success or error URL.
   • The webhook can also be utilized to retrieve payment status.

Testing, Test Cards, and Test Environment

1. Is there an endpoint to check whether a payment has been successfully captured or not in the test environment?

   • The webhook can be used to check if a payment has been successfully captured. However, this API will only function with production details for actual capture checks. For testing, simulate responses.

2. Are there any test credit card credentials available for testing UPayments' payment processing features?

   • Yes, please refer to the Test Cards page for detailed test card information.

Refund Process

1. Can we have more than one partial refund for the same transaction?

   Yes, you can have more than one partial refund on a single transaction until the remaining amount is fully refunded.

2. How long after a transaction can we do a refund? Can we do a refund after 1 year?

   KNET Refunds: Refunds can be initiated up to 6 months after the payment. Credit Card Refunds: There are currently no restrictions, and refunds can be done even beyond 2 years.

3. Can we do a refund for more than the actual value of the transaction?

   No, you cannot refund more than the original transaction value. We have a validation process in place to prevent such occurrences.

4. What happens if a refund is initiated two days after the settlement, when there is no longer a balance in the merchant account?

   In this scenario, you would need to top up your account balance before you can successfully perform the refund.