UPayments
UPayments is a hosted checkout built around Kuwait — KNET, cards, Apple Pay and the other methods enabled on your UPayments account. Shoppers pay on UPayments' page and return to your store. Which methods appear is decided in your UPayments account, not in TakeTheme.
Connecting
Settings → Payments → UPayments.
| Credential | Required | Where to find it |
|---|---|---|
| API Key | Yes | Your UPayments API key (a Bearer token) for the environment you pick below |
| API Secret Key | Recommended | UPayments dashboard → Merchant API Details |
| Environment | Yes | Sandbox (testing) or Live (production) |
Sandbox and production use different keys on different servers, so the key and the environment have to match. Start on Sandbox with your sandbox key and a UPayments test card, then switch to Live (production) with your production key. To get production keys, contact UPayments (support@upayments.com); your account has to pass their KYC review before it can take real payments.
The API Secret Key is optional but worth adding:
- UPayments requires every API request to be signed when HMAC is enabled on your account. With the secret saved, TakeTheme signs each request; without it, requests go out unsigned and an account that enforces signing will reject them.
- It lets TakeTheme verify the webhooks UPayments sends (see Payment flow).
Orders are created when the shopper returns from UPayments: TakeTheme looks the payment up with UPayments on the way back, so nothing needs to be registered for the normal flow. TakeTheme also gives UPayments a notification URL with every payment, which creates the order if the shopper pays and then closes the tab, or if the bank confirms late.
Settings
| Setting | Default | What it does |
|---|---|---|
| Checkout label | empty | Customer-facing name at checkout (e.g. "KNET or card"). Blank shows "UPayments" |
| Transaction fee | none | Flat or percentage surcharge added to the order when this method is chosen |
| Payment discount | none | Discount applied when the shopper picks this method |
| Send payment confirmation email | on | Emails the customer when payment succeeds |
| Notify on payment failures (emails) | empty | Alerts your team when a checkout fails |
Currency
TakeTheme creates the payment in your store currency. UPayments accepts KWD, SAR, USD, BHD, EUR, OMR, QAR, AED, INR, GBP and JOD, and converts anything other than KWD itself. Using a currency other than KWD may need to be switched on for your account by UPayments. A store currency UPayments doesn't support — for example EGP — shows UPayments' own error at checkout instead of a payment link.
KWD, BHD, OMR and JOD amounts are sent with three decimal places, other currencies with two.
If UPayments reports a captured amount that differs from the order total, TakeTheme logs the difference for reconciliation but does not reject the payment.
Payment flow
- Shopper picks UPayments and submits the checkout.
- TakeTheme creates a UPayments payment (tagged with an internal reference) and redirects the shopper to UPayments' hosted page.
- Shopper chooses a method and pays.
- UPayments sends the shopper back to TakeTheme —
GET /v1/payment/upayments/return/<reference>after a payment, orGET /v1/payment/upayments/cancel/<reference>if they cancel. TakeTheme looks the payment up with UPayments using your key and the session it stored when it created the payment — never anything from the browser — and, only if UPayments reports it CAPTURED, creates the order, already Paid. - The shopper lands on your store's thank-you page.
UPayments also POSTs a notification:
POST https://<your-api-host>/api/v1/payment/webhook/upayments
When you have saved an API Secret Key, every delivery must carry a valid X-Signature (HMAC-SHA256 over the timestamp, method, full URL and raw body, keyed with that secret); an unsigned or mismatched delivery is rejected with 403. Even a valid delivery never decides the outcome by itself: it only identifies the payment, and the status is re-read from UPayments. Whichever of the return and the notification arrives first creates the order — never both.
Failed, cancelled and late payments
- A payment that was declined, failed, cancelled or errored sends the shopper back to Payment Failed, where they can try again; no order is created.
- A shopper who backs out of the UPayments page before trying to pay also lands on Payment Failed. The payment itself is not marked failed, so if a payment still goes through afterwards, UPayments' notification creates the order.
- A payment that is still pending (waiting for 3-D Secure, or an authorization) is treated as not decided yet — the store keeps checking rather than telling the shopper it failed.
- KNET can confirm late — UPayments may take up to about 13 minutes to settle some KNET payments. The notification creates the order when it does, even if the shopper has left.
While a payment is pending, the thank-you page checks with UPayments at a limited pace, because UPayments allows only 30 status lookups per minute per key and blocks the key above that. The shopper's return and UPayments' notification are never held back by this.
Language
UPayments' page opens in English; the shopper can switch language there.
Refunds
Refunds are recorded in TakeTheme only — no refund call reaches UPayments. Issue it in the UPayments dashboard and record it here. See Refunds.
Troubleshooting
Checkout says UPayments rejected the API key. The key doesn't match the Environment. Sandbox keys only work on Sandbox and production keys only on Live (production). Re-save the key with the right environment.
Checkout says UPayments rejected the request signature. The API Secret Key is wrong, or belongs to a different environment than the key. Copy it again from Merchant API Details. If the message says the signature expired, the server clock is out of sync — contact support.
Checkout says the currency is invalid or not supported. UPayments doesn't take your store currency (see Currency). For a non-KWD currency, ask UPayments to enable multi-currency on your account.
The shopper paid but no order appeared.
Open the order's payment record: if looking the payment up could not reach UPayments, the storefront keeps checking and the order appears as soon as it can; a KNET payment confirmed late appears when the notification arrives. A 403 in the webhook log means the delivery's signature didn't match your saved API Secret Key — re-save it.
A payment method is missing from the UPayments page. Methods are enabled per account on UPayments' side; TakeTheme sends no method filter.