Skip to main content

HyperPay Payment Gateway

The ECOSIRE HyperPay Payment Gateway module adds a native Odoo payment.provider for HyperPay, the SAMA-licensed Saudi payment gateway built on OPPWA / COPYandPAY infrastructure. Customers complete checkout inside the embedded COPYandPAY widget; payment results are always re-verified server-side -- the browser result is never trusted on its own. Supports mada (Saudi national debit), Visa, Mastercard, and AMEX with full and partial refunds, HMAC-SHA256 webhook verification, and encrypted credential storage.

Compatibility: Odoo 17 / 18 / 19 Price: $249 (one-time) License: Up to 3 domain activations

Key Features​

  • COPYandPAY redirect/widget checkout (two-phase: prepareCheckout server call + client-side widget)
  • Server-side payment confirmation -- GET /v1/checkouts/{id}/payment is always called after the widget completes; the browser return is never the final authority
  • mada national debit scheme with a dedicated entityId (required for KSA merchants under SAMA regulations)
  • Visa, Mastercard, and AMEX international card brands
  • Full and partial refunds via paymentType=RF on any captured payment
  • Webhook handler at /payment/hyperpay/notify with HMAC-SHA256 signature verification
  • Test / Live environment switch driven by the provider state (Test vs Enabled)
  • All credentials (access_token, entityId fields) stored as encrypted provider fields, visible only to base.group_system
  • ECOSIRE license enforcement on checkout, API, and refund entry points
  • Supported currencies: SAR, AED, USD, EUR, JOD, EGP, BHD, KWD, OMR, QAR

Prerequisites​

  • Odoo 17, 18, or 19 (Community or Enterprise edition)
  • An active ECOSIRE license for this module
  • A HyperPay merchant account (contact HyperPay to start onboarding)
  • From HyperPay merchant onboarding: an Access Token (Bearer) and one or more Entity IDs (one per card brand: Visa/MC, mada, AMEX)
  • For KSA merchants: mada certification is a separate SAMA requirement -- confirm with HyperPay that your mada entity ID is provisioned before going live
  • For webhook notifications: ability to configure a callback URL in the HyperPay merchant dashboard
Live payments require a real merchant account

Test mode works with HyperPay sandbox credentials. No live charges can be processed until HyperPay has approved and activated your merchant account and issued production credentials.

STC Pay, Urpay wallets, Tamara / Tabby BNPL, and stored-credential server-to-server charges require additional merchant-specific provisioning by HyperPay. The connector raises a clear error for these features rather than silently failing.

Installation​

  1. Download the module ZIP from your ECOSIRE Dashboard
  2. Extract to your Odoo addons directory: 
    unzip ecosire-payment-hyperpay-*.zip -d /opt/odoo/addons/
  3. Restart the Odoo service: 
    sudo systemctl restart odoo
  4. Navigate to Apps, click Update Apps List
  5. Search for "ECOSIRE Payment | HyperPay" and click Install
  6. Enter your ECOSIRE license key when prompted

Configuration​

Step 1: Activate Your ECOSIRE License​

  1. Go to Settings > ECOSIRE License
  2. Enter the license key you received after purchase
  3. Click Activate -- the module features remain gated until this step succeeds

Step 2: Obtain HyperPay Credentials​

Complete HyperPay merchant onboarding to receive:

CredentialDescription
Access TokenStatic Bearer token sent on every API call. Issued per merchant account by HyperPay.
Entity ID (Visa / Mastercard)Channel identifier for international cards. Required.
Entity ID (mada)Dedicated channel identifier for the Saudi mada debit scheme. Required for KSA merchants.
Entity ID (AMEX)Channel identifier for American Express. Optional.
Webhook SecretShared secret for inbound webhook HMAC verification. Optional but recommended.

Test credentials (sandbox access token and test entity IDs) are provided by HyperPay when your sandbox account is created.

Step 3: Configure the Payment Provider in Odoo​

  1. Go to Accounting > Configuration > Payment Providers
  2. Find HyperPay in the list and click to open it
  3. Enter your credentials in the Credentials tab:
    • hyperpay_access_token -- Access Token (Bearer)
    • hyperpay_entity_id_visa_mc -- Entity ID (Visa / Mastercard)
    • hyperpay_entity_id_mada -- Entity ID (mada) (KSA mandatory)
    • hyperpay_entity_id_amex -- Entity ID (AMEX) (optional)
    • hyperpay_webhook_secret -- Webhook Secret (optional; used for HMAC-SHA256 signature verification)
  4. Set the provider state to Test to validate against the HyperPay sandbox
  5. Click Save

All credential fields are stored encrypted and are visible only to users in the System Administrator group.

Step 4: Configure Webhook and Return URLs​

Configure the following URLs in your HyperPay merchant dashboard:

URL typeValue
Webhook / Notification URLhttps://<your-domain>/payment/hyperpay/notify
Shopper Result URLSet automatically per transaction by the module

The webhook URL receives asynchronous payment notifications. The connector always re-fetches the authoritative payment status from HyperPay before processing -- the incoming notification is used only to trigger the server-side verification, not as the source of truth.

Step 5: Go Live​

  1. Verify at least one test payment succeeds end-to-end in Test mode
  2. Confirm your mada entity ID is provisioned (KSA merchants)
  3. Replace test credentials with your production Access Token and Entity IDs
  4. Set the provider state to Enabled

Usage​

Checkout Flow​

  1. The customer selects HyperPay at checkout and clicks Pay
  2. Odoo calls POST /v1/checkouts (prepareCheckout) server-side and receives a checkoutId
  3. The customer is redirected to the ECOSIRE checkout page hosting the COPYandPAY widget
  4. The widget renders the card form and handles 3DS / SCA challenges transparently
  5. On completion the widget posts to the return URL
  6. Odoo calls GET /v1/checkouts/{id}/payment server-side to retrieve the authoritative result
  7. On success the payment transaction moves to Done and Odoo records the payment

Refund Flow​

  1. Open the validated customer invoice in Accounting
  2. Click Credit Note (or use the refund button on the payment transaction)
  3. Odoo calls POST /v1/payments/{id} with paymentType=RF and the refund amount
  4. Full and partial refunds are supported; multiple partial refunds are allowed up to the original captured amount
  5. The refund transaction state updates to Done or Pending based on the gateway result code

API Details​

FieldValue
Auth methodBearer token (Authorization: Bearer {access_token})
Test base URLhttps://eu-test.oppwa.com
Live base URLhttps://eu-prod.oppwa.com
Checkout endpointPOST /v1/checkouts
Status endpointGET /v1/checkouts/{id}/payment
Payment / refund endpointPOST /v1/payments/{id} (paymentType=RF)
Webhook URL/payment/hyperpay/notify (on your Odoo domain)
Key credential fieldshyperpay_access_token, hyperpay_entity_id_visa_mc, hyperpay_entity_id_mada, hyperpay_entity_id_amex, hyperpay_webhook_secret

Troubleshooting​

IssueSolution
"Access token is not configured"Enter the Access Token on the HyperPay payment provider record under Accounting > Configuration > Payment Providers
"No entity ID configured for brand"The Entity ID for the card brand (Visa/MC, mada, or AMEX) is blank -- fill it in the provider credentials
Payment declined, result code 300.100.100The gateway requires 3DS / SCA re-authentication. Ask the customer to retry; the COPYandPAY widget will present the 3DS challenge
Webhook not triggeringVerify the Notification URL in your HyperPay dashboard is https://<your-domain>/payment/hyperpay/notify and is reachable from the internet
Webhook signature mismatch loggedConfirm the Webhook Secret field matches the shared secret in your HyperPay merchant dashboard exactly. The connector falls back to server-side re-fetch if the header is absent
Test payments succeed but live payments failEnsure the provider state is Enabled (not Test) and that your production credentials replace the sandbox ones
mada cards not acceptedConfirm the Entity ID (mada) field is filled and that HyperPay has provisioned your mada channel. mada requires separate SAMA certification
STC Pay / Urpay / Tamara / Tabby unavailableThese require additional merchant provisioning by HyperPay. The connector raises a clear error until HyperPay confirms and activates the relevant channel
"Could not reach the payment gateway"Check server outbound connectivity to eu-test.oppwa.com (test) or eu-prod.oppwa.com (live) on port 443
License not activeGo to Settings > ECOSIRE License and verify the key is activated. Checkout and refund are gated by the license

Support​

Last updated on