Merchant ID & API Tokens

How do I get my Merchant ID and API token from the UPayment Dashboard

Whitelabel API

How do I activate theWhitelabel API feature?
- To activate the Whitelabel API feature, please contact your UPayments Account Manager.
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

How can we fetchtrack_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.

ReturnUrl and CancelUrl

You will be redirected to the return URL for a successful payment (Captured) and the cancel URL for an unsuccessful payment (Not Captured), for example:
https://upayments.com/en/?payment_id=100527020000000598&result=CAPTURED&post_date=0927 &tran_id=527020000293353&ref=527020000040&track_id=019988a5066a999800a57eb83d309bafv2 &auth=B54978&order_id=019988a5066a999800a57eb83d309bae&requested_order_id=202210101255255144669 &refund_order_id=019988a5066a999800a57eb83d309bae&payment_type=knet&invoice_id=6058253 &transaction_date=2025-09-27%2003%3A09%3A49&receipt_id=019988a5066a999800a57eb83d309bae&trn_udf=User%20define%20data

Multimerchant API

How can sub-merchants receive deposits from transactions made on their platform?
- In the Multi-merchant feature, sub-merchants receive payments directly into their respective accounts.
Does theMultimerchant 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.
How do I split a customer payment between multiple merchants with a commission and delivery fee?
1. You can handle multimerchant payments using a single parent payment with an extraMerchantData array, which defines each merchant’s share and the admin’s commission.
  Steps to Calculate Commission and Delivery Fee Split:
  1. Calculate the total price of all merchant 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 merchants, 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:
```
{  
  "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 merchant 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 merchants, variable prices, delivery fees, and commission rates. Save Cards, KFAST
  - Submerchant IBAN number must be registered with UPayments in the submerchant account
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.
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

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.
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.
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.
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.
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

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.
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

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.

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.

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.

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.

Will I receive a webhook notification after a refund is created?

No, you will not receive a webhook notification after a refund is created.

How do I check the final status of a refund?

You will only receive the immediate API response when you submit the refund request. To check the final status, you must use the Refund Check Status API by calling it periodically (e.g., using a cron job).

Which ID should I use to trigger a refund?

Use the orderId. This identifier is consistent across all payment methods, including KNET, Credit Cards, and Apple Pay.

Are partial refunds supported?

Yes. Partial refunds are supported across all payment methods available in the Upayments ecosystem.

Does Upayments notify customers when a refund is issued?

No. Automated customer notifications (SMS/Email) for refunds must be handled by the merchant.

Integration & Security

Does the API support Idempotency Keys?

Not at this time. While we plan to implement Idempotency Keys in a future update, merchants are currently responsible for ensuring that a single refund request is not submitted multiple times (e.g., handling retries on your side).

Can I reuse my Magento module credentials for direct API calls?

Yes. The API credentials used for your Magento integration can be reused for direct server-to-server calls. All requests must use the Bearer token authentication scheme.

How are webhooks secured?

Our server-to-server webhooks are signed. We are currently rolling out HMAC signatures for enhanced security across our APIs.

Performance & Processing

Is the refund response synchronous or asynchronous?

Refund requests are queued for batch processing. Batches are processed every 4 hours.

How long does it take for a customer to receive their funds?

KNET: Approximately 4 business days.
Visa/Mastercard: Up to a maximum of 14 days.

What are the API rate limits?

The current rate limit for the Refund and Status-Query endpoints is 800 requests per minute.

Reporting

Can I get payout/deposit reports via API?

You can use our Sales Report API to track transaction data. Detailed deposit/payout reports are currently available exclusively through the Merchant Dashboard.

Plugins

WooCommerce

Q: How do I resolve issues with UPayment not appearing or functioning with the new WooCommerce Checkout Block?

A: The UPayment feature is currently not natively supported by the new WooCommerce Checkout Block experience. You can resolve this issue immediately by reverting your checkout page to use the classic WooCommerce shortcode.

Please follow these steps:

Checkout Block Workaround
Go to your Admin Dashboard.
Navigate to Pages -> Checkout -> Edit.
In the right corner of the editor, look for the three dots (...). Click on them and select "Code editor."
You will see a code block similar to this:

Important: Before making any changes, we highly recommend you copy this entire code and save it as a backup. (A backup of this page was also attached to the support email.)

Replace the entire existing code block with this single line:

Click "Save."
Refresh your checkout page to confirm that the UPayment option is now working correctly.

This action forces WooCommerce to use the traditional checkout structure, which is fully compatible with UPayment.

If you would prefer our support team to perform this configuration for you, please reach out with the necessary administrator credentials.

Plugin Version

The latest version of our plugin, which includes other recent stability fixes, can be found here: https://drive.google.com/file/d/1wuWfp4PdM8qlV0seroT2z2TGAPCs94Zu/view?usp=sharing