Connect your own HyperPay account so your customers can pay by card at checkout. This article covers the keys you need from HyperPay, each field on the Card payments page, the check we run with HyperPay when you save, and how to pause card payments or remove your keys.
Card payments are on Growth and up. See plans and what each includes. Connecting HyperPay needs the Edit settings permission, and seeing the page needs View settings. Out of the box only the Store owner role has them. See staff roles.
What you need from HyperPay: live keys, not test keys
You need a merchant account with HyperPay that HyperPay has approved. Once it is approved, HyperPay gives you the keys for its live system, the one that takes real cards:
- an entity ID;
- an access token;
- a webhook secret, for payment notifications.
HyperPay issues all three. The webhook secret comes when you add a webhook for your store's address in your HyperPay dashboard, or ask HyperPay's support to add it; the Card payments page shows the address. Card payments cannot be turned on without the secret.
Use only these live keys. We check every key against HyperPay's live system, so keys from HyperPay's test environment are always refused, and test keys never take a payment. The page says so in its first line: Enter the live keys HyperPay gives you once your account is approved; test keys do not take payments.
If you are still waiting for HyperPay to approve your account, carry on building your store meanwhile. Connecting HyperPay holds back only your first publish, not your designing. See HyperPay and your first publish.
Connect HyperPay
- In the sidebar, under Administration, open Card payments. You can also open the Card payments page (opens in a new tab) from here, or select Open card payments on the setup list on your dashboard.
- Under Address for HyperPay’s payment notices, copy your store's address. In your HyperPay dashboard, add a webhook with that address, or send it to HyperPay's support to add. HyperPay then gives you the webhook secret.
- In Entity ID, paste the entity ID from your HyperPay account.
- In Access token, paste your access token.
- In Webhook secret, paste your webhook secret.
- Leave Accept card payments at checkout ticked.
- Select Save. We save your keys, then check them with HyperPay straight away. It takes a moment.
When HyperPay accepts the keys, you see Card payment settings saved. and the badge turns to Connected. Your checkout can now take cards, provided Card payments is also ticked on the Commerce tab of Settings (see below).
Save stays greyed out until both Entity ID and Access token are filled in. Until your first save, the line Entity ID and access token are both needed to connect. stays beside it, even once Save is available. While Accept card payments at checkout is ticked, it also waits for the webhook secret, and the line Add the webhook secret to turn card payments on. says so.
The fields
| Field | Required | What it is |
|---|---|---|
| Entity ID | Yes | The identifier of your account at HyperPay. After saving it stays in its field, and you can edit it. |
| Access token | Yes | The secret key that lets your store open payments on your HyperPay account. Kept encrypted, and never shown again after you save. |
| Webhook secret | Yes, to accept card payments | The key HyperPay encrypts its payment notifications with. |
| Accept card payments at checkout | Ticked by default | Untick it to pause card payments without removing your keys. |
Entity ID
The identifier HyperPay gave you for your account; the placeholder shows how one starts, 8ac7a4c9…. Paste it exactly as HyperPay shows it. We remove spaces from the start and end, nothing else.
Unlike the two secrets, the entity ID is shown back to you. If you empty the field and save, your store is no longer connected.
Access token: kept encrypted, never shown again
The access token is what lets your store open a payment on your HyperPay account, so we treat it as a password. We store it encrypted, and once you save, no screen shows it again, not even to you. If you lose it, get it again from HyperPay.
After saving, the field is empty and its hint reads Stored key: followed by four dots and four characters, for example Stored key: ····Qm4x — leave blank to keep it. The four characters tell this stored key apart from another one, so you can see when it changes. They change every time you save an access token, even when you paste the same token again. They are not the last four characters of the token you typed.
Webhook secret
When a customer pays by card, HyperPay sends a payment notification to your store's address, encrypted with your webhook secret. Only that secret opens it, which proves it came from HyperPay, and that is how a card order is marked as paid the moment the customer pays.
We also ask HyperPay ourselves: when the customer comes back from the payment page, and every few minutes for a card order still Awaiting payment. A card checkout nobody completes is marked Failed after about an hour, and gives back the discount code use, gift card balance and points it was holding. It never took any stock: a card order takes its stock only once its payment is confirmed.
The secret is 64 letters and numbers. Paste it exactly as HyperPay shows it; anything else is refused with The webhook secret is the 64 letters and numbers HyperPay shows for your webhook. Copy it again.
You can save your keys with Accept card payments at checkout unticked while you wait for the secret. To turn card payments on, the secret has to be stored. While the box is ticked and no secret is stored or typed, Save stays greyed out, and the line Add the webhook secret to turn card payments on. says why.
If a save without the secret reaches us anyway, for example from a page left open in another tab, it is refused with Add the webhook secret from HyperPay before you turn card payments on. Once the secret is saved, its hint reads A secret is stored — leave blank to keep it.
Save: we check the keys with HyperPay
Every time you save a new entity ID or access token, we ask HyperPay to open a payment session with your keys and your store's currency. That is the same first step your checkout takes when a customer pays by card, so keys that pass the check are keys your checkout can use. Nothing is charged, and the session expires on its own.
Your keys are saved whatever HyperPay answers. The answer decides the message and the badge:
| Message | Badge | What it means |
|---|---|---|
| Card payment settings saved. | Connected | HyperPay accepted your keys. |
| Saved, but HyperPay did not accept these keys. | Not confirmed | Your keys are stored, but HyperPay refused them. A red box says why. |
| Saved. HyperPay could not be reached to confirm the keys. | Not confirmed | Your keys are stored, but HyperPay did not answer. Nothing suggests they are wrong yet. |
| You do not have permission to do this. | No change | Your role can open this page but not change it. Ask the store owner to add Edit settings to your role (see staff roles). |
| Could not save changes. | No change | Nothing was saved: the save did not go through. Try again in a moment. |
| Could not reach the server. Check your connection and try again. | No change | Your connection dropped and nothing reached us. What you typed stays in the fields: save again once you are back online. |
The message follows what is on record, not only what HyperPay said this time. If HyperPay has already refused your keys and you save without changing the entity ID or the access token, for example to tick the box or add the webhook secret, we ask HyperPay again. If it does not answer, you see Saved, but HyperPay did not accept these keys. again, with the same reply in the red box. If the reply has not changed, HyperPay may simply not have answered: wait a few minutes and select Check again before you change any key.
For the two Not confirmed answers, a Check again button appears beside Save. HyperPay did not accept my keys — what now? explains every refusal and what to do about it.
Connected and confirmed
The badge at the top right of the HyperPay card always shows where your connection stands:
| Badge | What it means |
|---|---|
| Not connected | No entity ID or no access token is stored. |
| Not confirmed | Both are stored, but HyperPay has not accepted them yet: it refused them, or it could not be reached. |
| Connected | HyperPay accepted the stored keys. |
The badge is about your keys only. It still reads Connected while card payments are paused, so check the Accept card payments at checkout box too.
Replace one key: leave the others blank
The Access token and Webhook secret fields open empty every time, even when keys are stored. Empty means keep: a blank secret field leaves the stored key as it is.
- Paste the new value into the field you are replacing, and leave the others as they are.
- Select Save.
A new entity ID or access token is checked with HyperPay again, and the badge shows the new answer. A new webhook secret alone, or a change to the tick box alone, does not ask HyperPay anything when your keys are already confirmed.
You cannot clear a stored secret by emptying its field. To take your keys out, remove them.
Accept card payments at checkout: pause without removing the keys
To stop taking cards for a while, for example while you sort something out with HyperPay:
- Untick Accept card payments at checkout.
- Select Save.
Your keys stay stored. The card option disappears from your checkout, and your storefront's footer stops showing card marks. To take cards again, tick the box and save; there is nothing to re-enter.
While card payments are paused:
- Payments already made are still confirmed. HyperPay's notification for a card order paid just before you paused is still accepted, and the order moves on as usual.
- Card refunds still work. A refund of an earlier card order uses the same keys, which pausing keeps.
- You cannot pause while cash on delivery is off. Card payments would then be your store's only way to be paid, so saving is refused with Card payments are this store's only way to be paid. Turn cash on delivery on in Settings first.
- Before your first publish, the setup list shows Connect HyperPay as Turned off, and publishing waits.
The Card payments switch on the Commerce tab
There is a second switch for cards: the Card payments box under Checkout payments, on the Commerce tab of Settings. It is the store-wide choice of which methods your checkout offers. The card option appears at checkout only when:
- Card payments is ticked on the Commerce tab;
- your keys are stored on the Card payments page, and HyperPay has confirmed them (the badge reads Connected);
- the webhook secret is stored;
- Accept card payments at checkout is ticked there;
- your plan includes card payments.
If any one of these is missing, your checkout and your storefront's footer show no card option, and customers pay cash on delivery.
Both boxes start ticked. Use the Commerce tab when you decide which payment methods your store offers, and the tick box on this page when you only need to pause cards for a while.
To take cards only, untick Cash on delivery (COD) on the Commerce tab. Card payments are then your store's only way to be paid, so they have to work first: until HyperPay is connected, confirmed, holding its webhook secret and switched on here, the tab says Cash on delivery can only be turned off once card payments are connected, confirmed by HyperPay and turned on in Card payments. and does not save. See set tax, payment methods and guest checkout.
HyperPay and your first publish
On Growth and up, Connect HyperPay is a task on your setup list, and your storefront cannot be published until it is done. It is done when your keys are stored, Accept card payments at checkout is ticked, the badge reads Connected and the webhook secret is stored. Until then the task shows what is missing:
| Shown under Connect HyperPay | What to do |
|---|---|
| Not connected | Enter your entity ID and access token, and save. |
| Turned off | Paste the webhook secret if none is stored yet, tick Accept card payments at checkout, and save. |
| Keys not confirmed by HyperPay | Fix the keys or select Check again. See HyperPay did not accept my keys. |
| Webhook secret not added | Card payments are on but no webhook secret is stored, which only a store connected before the secret became required can meet. Paste the secret, and save. See Webhook secret. |
Card payments cannot be turned on without the webhook secret, so keys you saved while you waited for it show Turned off until you paste it and tick the box. See Webhook secret.
On a published store, as here, the task is the Last step card, under the line Finish these to complete your store’s setup. Before your first publish, while other steps are still open, it waits under After that with the Needed to publish tag and the same grey line.
Before your first publish, once every other step is done, the list shrinks to the line Your store is ready to design, which then reads Design your storefront now, and connect HyperPay before you publish it., with Open card payments beside Open Storefront Studio.
This task holds back publishing only. Once the rest of your setup list is done, you can design your whole storefront in the Storefront Studio while you wait for HyperPay; only publishing waits for this task. Publish opens as soon as the task and the rest of the list are done; after an email sign-up, it also waits for the link we emailed you. After your first publish the task never holds your store back again, even if you later remove your keys. See the setup list before your first publish and save a draft and publish your storefront.
Remove your HyperPay keys
Removing deletes your stored entity ID, access token and webhook secret. Use it when you are leaving HyperPay or handing the store over; to stop cards for a while, pause them instead.
Removing is refused while a card order is still waiting for its payment, with A card order is still waiting for its payment. Pause card payments instead, and remove the keys once it is paid or cancelled., because the keys are what confirm it. It is refused too while Cash on delivery (COD) is unticked on the Commerce tab, with Card payments are this store's only way to be paid. Turn cash on delivery on in Settings first. Turn cash on delivery back on, then remove the keys.
- At the bottom of the page, in the Remove HyperPay keys card, select Remove HyperPay keys.
- In the dialog Remove your HyperPay keys?, select Remove HyperPay keys to confirm, or Cancel to keep them.
You see HyperPay keys removed. The page goes back to Not connected, with empty fields.
Warning
Removing cannot be undone, and we cannot give the keys back: to connect again you need them from HyperPay. Until you do, customers cannot pay by card, and card refunds of earlier orders cannot go through.
On Business and up, the Audit log records every change here as HyperPay keys added, HyperPay settings changed, HyperPay keys checked or HyperPay keys removed, with who did it. It never records the keys themselves. See the audit log.
On plans without card payments
On Free and Starter, Card payments in the sidebar carries a padlock. Selecting it shows a message naming the plan that includes card payments, with See plans. If you reach the page by its address, it says Your plan takes cash on delivery and Card payments come with a higher plan. Cash on delivery works on every plan., with See plans to open your Subscription page.
To take cards, move up to Growth or higher, then come back here to connect. See upgrade or change your plan.
How the money moves from your customer to your bank is in How customers pay you, and card refunds, which go back through HyperPay, in Refund an order in full or in part.
Next, choose which payment methods your checkout offers, or publish your storefront.