Telcell wallet payments on your website: setup, testing and what to watch

Telcell is the other wallet an Armenian shop is regularly asked for, alongside Idram. Adding it is not hard, but it is different from adding a card processor in ways that catch people out: the credentials are different, there is no test environment on the wallet side, and the confirmation you receive is the only account of what happened. Here is the whole picture, from contract to first live payment.

How a Telcell payment runs

For the buyer:

1. At your checkout they choose Telcell from the methods you have enabled for that domain. On the Paynet hosted checkout it is shown as a wallet, under the display name you chose.
2. They are taken to Telcell to pay, which is where anything sensitive happens. Nothing of it passes through your server.
3. Telcell confirms the payment, and the buyer comes back to the return_url you set when the payment was created.
4. Your store reads the real status from the API and only then marks the order paid.

For you, the merchant, the same journey has a different shape. You created a payment with an amount in whole AMD and your own order_id, you handed the buyer a checkout_url, and now you are waiting for a signed webhook that tells you the payment reached a final status. Everything else is bookkeeping.

What Telcell gives you

You sign with Telcell directly, and the wallet settles to you under that agreement. Paynet does not hold the money and does not resell the contract. What you receive from Telcell is a pair of credentials:

• a Shop ID
• a Shop Key

That is the entire credential set. Both go into the Telcell provider you add in your Paynet dashboard, and both are stored encrypted at rest. If someone offers to type them into a config file on your web server instead, that is a step backwards: the point of putting them in the gateway is that they live in one encrypted place rather than in every store you run.

Enabling Telcell in Paynet

1. Open Providers, choose Add provider, pick Telcell as the processor, give it a display name and paste the Shop ID and Shop Key.
2. Connect that provider to your verified domain. Providers are turned on and off per domain, so a provider you added but did not connect will not appear at anyone's checkout.
3. Check the Domains page. It shows the active payment methods per domain, and flags a domain that has none.

Two dashboard behaviours are worth knowing before you need them:

• Credential checks are honest about their limits. Some processors offer no way to verify credentials without taking a real payment. Where that is true, the dashboard says exactly that instead of showing a reassuring green tick it has not earned.
• Unreachable gateways are hidden, not left to fail. Paynet checks provider gateways hourly. If one cannot be reached three times in a row it is hidden from buyers until it answers again, because a real payment through it would fail anyway. You see the state in your dashboard, and the buyer sees the remaining methods rather than a broken one.

Testing without a wallet sandbox

Telcell does not offer a public test environment, and neither does Idram. You cannot rehearse against a fake Telcell. So split the problem in two.

Step one: prove your integration with the Sandbox provider. Install the Sandbox provider from your dashboard and send "processor": "sandbox", or create an API key in the test environment, which starts with sk_test_ and turns every payment made with it into a sandbox payment. No provider is contacted, no money moves, nothing is billed or counted. On the test checkout the card number decides the result:

• 4111 1111 1111 1111 approved
• 4000 0000 0000 0002 declined by issuer
• 4000 0000 0000 0069 insufficient funds
• 4000 0000 0000 0119 processor timeout
• 4000 0000 0000 0259 transaction expired
• 4000 0000 0000 0309 processor unavailable

Any other 16-digit number is approved, and expiry, CVV and cardholder name are not checked. Test payments show under the Test tab in your dashboard and fire webhooks with livemode: false, so you can prove the whole path, including your failure handling, before a single dram moves. The Sandbox provider also works inside the CMS plugins, so a storefront can be tested exactly as a buyer would use it.

Step two: prove the Telcell credentials with one small live payment. Sandbox tells you your code is right. It cannot tell you whether your Shop Key was typed correctly. When the sandbox run is clean, pay yourself a small amount through Telcell for real. Payments under 500 AMD are free on the Paynet side, so the rehearsal costs you nothing beyond whatever your own contract charges.

Confirmation: the part to get right

Telcell, like Idram, exposes no status API that can be polled after the fact. There is no way to ask the wallet later what really happened, so the confirmation path has to be sound the first time.

Follow the same discipline the API is built around:

• Never trust the redirect. A buyer landing on your thank-you page proves a browser navigated, nothing more.
• Verify the signature. X-Paynet-Signature is the lowercase hex HMAC-SHA256 of the raw request body under your webhook secret. Hash the raw bytes, compare in constant time, and reject anything that does not match. During a secret rotation, X-Paynet-Signature-Next carries the signature under the new secret for 24 hours, so accept either.
• Dedupe on delivery_id, then answer 200 quickly. Paynet waits 10 seconds for a 2xx and retries three times, after 1, 5 and 30 minutes.
• Pull the truth. Call GET /api/v1/orders/{order_id}/payment and act on what it returns. It gives you the most decisive payment for that order, so a final record wins over a stale pending one.
• Expect late news. An unpaid payment expires after 20 minutes, but a late confirmation can still move a failed or expired payment to completed. Always act on the latest state, not the first webhook you saw.

Copy-ready verification code in PHP and Node.js is in the API reference, and the same flow is summarised on the developer page.

Refunds and other promises to buyers

Before you write a refund policy that mentions instant reversals, check what the method supports. The refund endpoint returns refund_not_supported when a processor cannot process a refund through the gateway, and refund_in_progress, already_refunded or processor_unavailable when it can but the moment is wrong. Wire those codes into a human sentence in your admin, so support staff know whether to wait or to arrange a transfer by hand. On the Paynet side refunds themselves are free, and refunding does not give back the transaction unit you spent: it was a successful payment when it happened.

Telcell in the store plugins

If your shop runs on WooCommerce, OpenCart 2, 3 or 4, PrestaShop, Tilda or Ecwid, you do not write any of this yourself. Install the plugin or enable the connector, click Connect once, and every processor you have connected in Paynet shows up at checkout as its own named option. The plugins treat a webhook as a hint and pull the authoritative status from your Paynet account before completing an order, so a forged notification cannot mark an order paid. Platform-by-platform instructions are on the plugins page.

What to do next

• Ask Telcell for your Shop ID and Shop Key if you have not received them.
• Add Telcell as a provider in Paynet and connect it to your verified domain.
• Run a full sandbox pass, including at least one declined and one timed-out payment, so your failure path is real code and not a guess.
• Take one live payment under 500 AMD through Telcell and confirm it lands as paid in your store, in your dashboard, and on a fiscal receipt if e-HDM is active.
• Decide what your admin does with each refund error code before a customer asks.
• Anything unclear, write to [email protected].

Telcell is a trademark of its owner. Paynet is an independent payment gateway operated by Digital Brains LLC in Yerevan; merchants hold their own contracts with each wallet and bank.