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.

5. How can I detect and handle success, failed or canceled payments?

   There are three primary methods to detect successful, failed, or canceled payments with Upayment:

   1. Redirect URLs: returnUrl and cancelUrl
      When you initiate a charge request, you should provide both a returnUrl for successful payments and a cancelUrl for failed or canceled transactions. After a customer completes the payment process on our gateway, they will be redirected back to the specified URL with query parameters that indicate the payment status. Your application can then read these parameters to display the correct status to the user.

   2. Webhook Notifications: notificationUrl
      We highly recommend using webhooks for a more reliable and secure way to update your backend system. By providing a notificationUrl in your charge request, you're setting up a webhook endpoint on your server. The Upayment gateway will send an asynchronous POST request to this URL whenever a payment is captured or not captured, including details about the transaction. This method is ideal for updating your database with the final payment status, as it's not dependent on the user's browser redirection.

   3. Get Payment Status API
      If you need to check the status of a specific payment at any time, you can use the Get Payment Status API. This API allows you to query the status of a transaction using its unique ID, providing a reliable way to verify the outcome of a payment, regardless of the user's actions or any redirection issues. This is especially useful for reconciliation purposes or for cases where the webhook notification might have been missed.
      
      
      These three methods—redirect URLs for immediate user feedback, webhooks for backend system updates, and the API for on-demand status checks—provide a comprehensive solution for handling all payment outcomes.

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.