Tap Payments Gateway

The ECOSIRE Tap Payments module integrates Tap Payments — the leading payment gateway across the GCC — directly into Odoo as a native payment provider. It slots into eCommerce checkout, the Sales and Invoicing payment flow, and the customer portal with no custom checkout code required. 3-D Secure is enforced by default in compliance with GCC card-not-present regulations, and every payment is confirmed both on the customer return and via an asynchronous signed webhook.

Compatibility: Odoo 17 / 18 / 19 Price: $249 (one-time) License: LGPL-3 — up to 3 domain activations via ECOSIRE License

Try Before You Buy

A live demo is available. Contact [email protected] to request access.

Key Features

• Native payment.provider (code tap) — appears under Invoicing > Payment Providers
• Redirect checkout flow: POST /charges creates the hosted payment page; the customer is redirected back after 3DS completion
• 3-D Secure mandatory by default (GCC regulatory requirement — never silently disabled)
• Payment status confirmed by GET /charges/{id} on customer return and by asynchronous webhook — dual confirmation prevents missed payments if the browser is closed mid-flow
• HMAC-SHA256 webhook signature verification via the Tap hashstring header — payloads with invalid signatures are rejected with HTTP 400
• Full and partial refunds (POST /refunds) wired to Odoo's standard refund flow
• Idempotency-Key on every charge (Odoo transaction reference) — no double charges on network retry
• Multi-currency: SAR, KWD, AED, BHD, QAR, OMR, EGP, JOD, USD (KWD/BHD/OMR 3-decimal handling)
• Secret keys stored encrypted with groups='base.group_system' — never stored in plain text or hardcoded
• Sandbox mode via sk_test_* keys; live mode via sk_live_* keys — same API host, no separate sandbox URL

Supported Payment Methods

Method	Country	Notes
Credit / Debit Cards (Visa, Mastercard, Amex)	SA, KW, AE, BH, QA, OM, EG, JO	Default; enabled for all merchants
mada	SA	Saudi domestic debit — requires mada activation in Tap dashboard
KNET	KW	Kuwaiti national debit — redirect-based
Benefit	BH	Bahraini national payment network
OmanNet	OM	Omani national debit network
Apple Pay	SA, AE, KW, BH, QA	Requires Apple Pay domain verification via Tap dashboard
STC Pay	SA	Saudi mobile wallet — OTP redirect
Fawry	EG	Egyptian offline/USSD payment

Domestic schemes and wallets

mada, KNET, Benefit, OmanNet, Apple Pay, and STC Pay each require explicit activation in the Tap Business Dashboard. Once activated, Tap routes to the correct method automatically based on card BIN or customer selection — no additional Odoo configuration is needed.

Prerequisites

• Odoo 17, 18, or 19 (Community or Enterprise edition)
• An active ECOSIRE license for this module
• A Tap Payments merchant account — sign up at tap.company
• For live charging: a Tap merchant account approved for production transactions in your target GCC country

Installation

1. Download the module ZIP from your ECOSIRE Dashboard
2. Extract to your Odoo addons directory:

   unzip ecosire-payment-tap-*.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 | Tap Payments" and click Install
6. Activate your ECOSIRE license when prompted (go to Settings > ECOSIRE License)

Configuration

Step 1: Obtain API Keys from the Tap Business Dashboard

1. Log in to your Tap Business Dashboard
2. Navigate to Developer > API Credentials
3. Copy your Secret Key — it starts with sk_test_ (sandbox) or sk_live_ (production)
4. Copy your Public Key — it starts with pk_test_ or pk_live_

Live charging requires a real merchant account

Test keys (sk_test_*) allow sandbox testing without real money movement. Switching to live keys (sk_live_*) requires a Tap merchant account that has completed onboarding and KYC for your country.

Step 2: Configure the Payment Provider in Odoo

1. Navigate to Invoicing > Configuration > Payment Providers

2. Find Tap Payments and click Edit

3. Enter your credentials:

   Field	Description
   tap_secret_key	Server-side secret key (sk_test_* or sk_live_*). Stored encrypted; visible only to system administrators.
   tap_public_key	Client-side publishable key (pk_test_* or pk_live_*). Displayed to the browser for Tap.js card tokenization.
   tap_webhook_secret	Optional. If set, this key is used to verify webhook HMAC signatures. If left blank, the Secret Key is used (which is the Tap default).

4. Set the State to Test (sandbox) or Enabled (live)

5. Click Test Credentials to validate your keys — the module checks the key prefix format and reports whether you are in sandbox or live mode

Step 3: Configure Webhook and Return URLs in Tap Dashboard

The module exposes two fixed controller URLs that must be registered in your Tap Business Dashboard:

Purpose	URL
Customer return after payment	https://<your-odoo-domain>/payment/tap/return
Asynchronous webhook	https://<your-odoo-domain>/payment/tap/webhook

To register the webhook URL:

1. In the Tap Business Dashboard, go to Developer > Webhooks
2. Add https://<your-odoo-domain>/payment/tap/webhook as the endpoint URL
3. Select the event types you want to receive: CAPTURED, AUTHORIZED, VOIDED, REFUNDED, FAILED, CANCELLED
4. Save

Webhook registration is manual

Programmatic webhook registration (POST /webhooks) is not automated in this module — configure the webhook URL directly in the Tap Business Dashboard as shown above.

Step 4: Publish the Provider

1. Back in Odoo, click Publish on the Tap Payments provider to make it available on your eCommerce checkout and customer portal

Usage

Checkout Flow

1. The customer selects Tap Payments at checkout and clicks Pay
2. Odoo calls POST /charges to create a charge object with 3DS enforced and the Odoo transaction reference as the idempotency key
3. The customer is redirected to the Tap-hosted payment page where they complete the card entry, 3DS verification, or wallet payment
4. After payment, Tap redirects the customer back to /payment/tap/return
5. Odoo confirms the status by calling GET /charges/{id} — the return payload alone is not treated as authoritative
6. Tap also sends an asynchronous webhook to /payment/tap/webhook; the signature is verified with HMAC-SHA256 before the transaction state is updated

Processing Refunds

1. Open the paid invoice or the payment transaction in Odoo
2. Click Refund (for partial refund, enter the amount)
3. Odoo calls POST /refunds on the original charge ID
4. The refund transaction is created in Odoo and the status is updated when Tap confirms

API Details

Field	Value
Auth method	Bearer API Key (Authorization: Bearer sk_live_* or sk_test_*)
Base URL	https://api.tap.company/v2
Sandbox	Same base URL as production; mode is selected by key prefix (sk_test_* vs sk_live_*)
Charge endpoint	POST /charges (verified)
Status poll	GET /charges/{id}
Refund endpoint	POST /refunds (verified)
Webhook signature	HMAC-SHA256 via hashstring header (verified)
Supported currencies	SAR, KWD, AED, BHD, QAR, OMR, EGP, JOD, USD
Key config fields	tap_secret_key, tap_public_key, tap_webhook_secret

Limitations and Honest Stubs

The following features raise a clear UserError rather than calling an unverified endpoint. They are not silently ignored.

Feature	Status
Authorize / Manual Capture (two-step)	Not supported — the capture endpoint path requires a live merchant account to verify
Void an authorization	Not supported — void path requires merchant-account verification
Saved cards / customer tokens	Not supported — requires Tap.js client-side tokenization setup beyond the current scope
Payment links (POST /invoices)	Not supported in this version
PK wallets (JazzCash, Easypaisa)	Not available — these require Tap integrator-gated onboarding and are not exposed through the standard Tap API contract
Programmatic webhook registration	Not automated — configure via Tap Business Dashboard

Troubleshooting

Issue	Solution
"A Tap Secret Key is required before enabling"	Enter tap_secret_key on the provider form before setting State to Test or Enabled
Signature mismatch (webhook rejected with 400)	Verify that tap_webhook_secret matches the secret used when setting up the webhook in the Tap dashboard; if left blank, the module uses tap_secret_key for HMAC verification
Payment redirects to Tap but returns "unknown status"	The charge ID was not resolved — check that the Odoo return URL (/payment/tap/return) is publicly accessible and that CSRF is not blocking the GET request
Tap provider not appearing at checkout	The provider State may be set to Disabled, or the transaction currency is not in Tap's supported list (SAR, KWD, AED, BHD, QAR, OMR, EGP, JOD, USD)
Sandbox charges appear real	Confirm your Secret Key starts with sk_test_ — live keys (sk_live_*) create real charges immediately
mada / KNET / Benefit not offered to customers	These domestic schemes require activation in the Tap Business Dashboard; contact Tap support to enable them on your merchant account
Apple Pay not appearing	Apple Pay requires domain verification and merchant identity certificate registration through the Tap dashboard
"Manual capture is not yet supported" error	The module uses direct charge (auto-capture) only; two-step authorize/capture is not yet available
License error on payment attempt	Verify your ECOSIRE license is active at Settings > ECOSIRE License

Support

• General Troubleshooting
• Email: [email protected]
• Support Portal