> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komerza.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup TagadaPay

> Accept card payments on Komerza through your own TagadaPay account

Accept **credit and debit cards** through your own **TagadaPay** account. TagadaPay is a payment orchestrator: you connect the processors you already have (Stripe, NMI, Airwallex, Checkout.com and others) or use TagadaPay's own managed acquiring, and TagadaPay routes each charge to one of them. Komerza takes the card on your checkout, charges it through TagadaPay with your API key, and delivers the order. Funds settle wherever your processor settles them - Komerza adds nothing on top.

Komerza connects using a TagadaPay **API key**. Komerza registers its own **webhook** on your TagadaPay store when you link it, so there is nothing to copy back and forth.

> [!NOTE]
>
> TagadaPay's own documentation refers to the same screens by different names - the key you need is under **Settings → Access Tokens** in some places and **Settings → API Keys** in others, and the dashboard is at [app.tagada.io](https://app.tagada.io) even where their help centre links to `crm.tagadapay.com`. The steps below use the names the dashboard shows today and note the aliases where they differ.

## Prerequisites

* A [TagadaPay account](https://app.tagada.io) with a payment method on file. TagadaPay asks for one when you create the account; you are not billed until you start processing. Their help centre walks through it: [Create an Account on Tagada](https://help.tagada.io/en/articles/20-create-an-account-on-tagada).
* At least one **processor** connected and **enabled** in your TagadaPay organisation, and a **payment flow** on the store that is set **active**. A store without an active flow declines every card, even when TagadaPay's setup checklist shows the store as complete. Steps 1 and 2 cover both.

**1. Connect a processor in TagadaPay**

A processor is TagadaPay's connection to whoever actually moves the money - your Stripe account, your NMI gateway, or TagadaPay's managed acquiring.

1. Log into [app.tagada.io](https://app.tagada.io). Make sure you are in your **Organization** (not inside a store), then open **Payment Flows** in the left-hand menu and go to the **Processors** tab.
2. Click **Add Processor**, pick your processor and click **Next**. If yours is not listed, TagadaPay asks you to contact your account manager.
3. Enter the credentials it asks for and click **Save Changes**. What each processor needs is listed in TagadaPay's [Processor Credentials](https://docs.tagada.io/developer-tools/node-sdk/processor-credentials) reference - for Stripe it is the secret and publishable keys, for NMI the API security key.
4. Make sure the **Enabled** checkbox is ticked. A processor that is saved but not enabled counts as connected on TagadaPay's checklist and still cannot take a charge.

> [!NOTE]
>
> **Testing first?** Add a processor of type **Sandbox** instead. It approves any 16-digit card number (`4242 4242 4242 4242` with any future expiry and CVC) and charges no real money, so you can run the whole flow before you connect a live processor. TagadaPay's help centre: [Connect Sandbox Account on Tagada](https://help.tagada.io/en/articles/50-connect-sandbox-account-on-tagada).

Source: [Add Processors to Your Organization](https://help.tagada.io/en/articles/19-add-processors-to-your-organization) in TagadaPay's help centre.

**2. Create a store and give it an active payment flow**

Charges are taken on a TagadaPay **store**, and a store only charges through a **payment flow** that names your processors. If you already have a store with an active flow, skip to step 3.

1. In TagadaPay, click **Stores** in the left-hand menu, then **Add Store**. The name, logo and colour are only visible to you.
2. Choose the store's currencies. The **Charge Currency** is the one TagadaPay charges in; Komerza reads the store's charge currencies when you link it and will only charge in one of them. Komerza converts prices from your store's own currency when they differ.
3. Click **Create Store**.
4. Open the store, go to its **Payment** tab and click **Create Your First Flow**, then **Edit Flow**.
5. Name the flow, pick a **Routing Strategy** and your **Primary Processors**. With one processor, give it the full weight. **Fallback** and **Abuse Detection** are optional - fallback retries a declined charge on a second processor if you connected one.
6. **Set the flow as active.** TagadaPay's own instructions flag this as the step people miss, and a store whose flow is not active declines every card.

Sources: [Create Your Store on Tagada](https://help.tagada.io/en/articles/21-create-your-store-on-tagada) and [Create a payment flow for your Store](https://help.tagada.io/en/articles/112-create-a-payment-flow-for-your-store-v1).

**3. Create a TagadaPay API key**

1. Click your avatar in the top-right corner and choose **Settings**.
2. Open **Access Tokens** - TagadaPay's other documentation and help centre call this section **API Keys**; it is the same page. If you cannot see it, your TagadaPay account role does not allow it: ask the account admin, or TagadaPay support at `api-support@tagadapay.com`.
3. Click **+ Create Access Token** (or **Create API Key**), name it `Komerza`, and copy the key. Keys are either a UUID (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) or start with `sk_crm_`; Komerza accepts both.

> [!WARNING]
>
> The key needs **admin** access to your TagadaPay organisation. Vaulting a card, running 3-D Secure and registering a webhook are all admin-only calls at TagadaPay, so a key with narrower permissions links fine and then fails at the first payment. If TagadaPay offers you a choice of permissions, give the key full access.

Source: [Get an API key](https://docs.tagada.io/developer-tools/node-sdk/get-api-key) (TagadaPay developer docs) and [Getting started with the Node SDK](https://help.tagada.io/en/articles/65-getting-started-with-the-node-sdk) (help centre).

**4. Connect TagadaPay to Komerza**

1. In your Komerza dashboard, open **Settings** under **Online Store**, then go to **Payment Methods**.
2. Under **Available Payment Methods**, find **TagadaPay** and click **Connect**.
3. Paste your **API key** from step 3.
4. Click **Look up stores**. Komerza checks the key with TagadaPay and lists the stores it can see. With one store, it is selected for you; with several, pick the one from step 2.
5. Choose your options:
   * **Require Billing Information** - ask customers for their billing address before they pay. Improves issuer approval rates and 3-D Secure outcomes, at some cost to conversion.
   * **Enable 3D Secure** (on by default) - authenticate the cardholder through TagadaPay's card vault before charging. Leave it on unless your processor runs its own 3-D Secure and you have been told to turn it off.
   * **Always request a challenge** - ask the issuer to challenge every payment rather than deciding itself. Stronger liability shift, more friction; the issuer still has the final say.
6. Click **Save changes**.

Komerza registers a webhook on your TagadaPay store as part of saving, subscribed to the payment succeeded, failed, rejected and refunded events. You can see it in TagadaPay under the store's **Integrations → Webhooks**, and every delivery TagadaPay has made to it under **Deliveries** there. Leave it in place.

**5. Test the connection**

Place a small test order on your store, pick the card option at checkout and pay. Confirm the order is marked paid and delivered before you go live. If you connected a **Sandbox** processor in step 1, use `4242 4242 4242 4242` and no real money moves; swap the flow to your live processor afterwards.

## How it works

1. A customer picks the card option at checkout and enters their card on your Komerza checkout. The card number goes straight from their browser into TagadaPay's card vault; it never touches Komerza.
2. Komerza turns the vaulted card into a payment instrument on your TagadaPay store and, with 3-D Secure on, the customer's bank authenticates them. Some processors (Stripe among them) host that step on their own page and send the customer back to your checkout afterwards.
3. Komerza charges the instrument through TagadaPay, which routes the charge to a processor according to your payment flow.
4. On approval Komerza marks the order paid and delivers it straight away. If the charge finished away from the checkout, TagadaPay's webhook tells Komerza, and the order is delivered from that.

## Managing payments

* **Refunds** - Issue a full refund from the order in Komerza. Komerza refunds the payment through TagadaPay, which passes it to the processor that took the charge.
* **Declines** - The reason a card was declined is in TagadaPay: open **Payments** in your organisation, click the payment, and scroll to **Transaction Information** ([Check Declined Payment Reasons](https://help.tagada.io/en/articles/34-check-declined-payment-reasons)). A card the issuer tells us never to present again is blocked for the rest of that order; the customer starts a new checkout with another card.
* **Chargebacks** - TagadaPay does not send a webhook when a dispute is opened; disputes are handled in TagadaPay and with your processor. Record the dispute on the order in Komerza yourself so the books match.

## Troubleshooting

| Problem | Fix |
| - | - |
| "TagadaPay refused this API key" | Check the key was copied whole and belongs to your live TagadaPay account at app.tagada.io - a key from TagadaPay's separate staging host is refused. |
| "TagadaPay refused to register our webhook" | The key does not have admin access to the organisation. Create a new key with full permissions (step 3) and paste it in. |
| "This TagadaPay account has no store yet" | Create one (step 2) - the key is fine. |
| Every card is declined | The store has no **active** payment flow, or the flow's processor is not **Enabled**. Open the store's **Payment** tab in TagadaPay and check both; TagadaPay's setup checklist can show green with either of these wrong. Then check the decline reason under **Payments**. |
| "This store is not taking card payments at the moment" | TagadaPay reports the merchant as closed. Open your organisation in TagadaPay and check the account's status with your account manager. |
| Payment finished on the bank's page but the order is still unpaid | The webhook was not delivered. In TagadaPay, open the store's **Integrations → Webhooks → Deliveries** and look for the failed delivery. TagadaPay disables a webhook that fails for three days straight; re-enable it there, or unlink and relink TagadaPay in Komerza to register a fresh one. |
| Charges happen in the wrong currency | Komerza only charges in a currency on the store's **Charge Currency** list in TagadaPay. Add the currency there, then unlink and relink TagadaPay in Komerza so it re-reads the list. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.