PostFinance
Connect PostFinance to PayLexer to accept cards, TWINT, PostFinance Card and e-finance payments across Switzerland and Europe, and issue full or partial refunds.
PostFinance is Switzerland's state-owned retail bank, and PostFinance Checkout is the payment gateway it offers to online merchants. It is the processor Swiss shoppers expect, aggregating the local payment methods most Swiss adults already hold - PostFinance Card, PostFinance e-finance and TWINT alongside international cards, PayPal and SEPA Direct Debit. PayLexer redirects your shoppers to PostFinance's own hosted payment page, so card data never touches your website or PayLexer.
- Supported Regions (Merchant Accounts): Switzerland, Liechtenstein, Austria, Germany and neighbouring European markets - view full list
- Supported Currencies: CHF, EUR, AUD, CAD, DKK, GBP, JPY, NOK, SEK, USD
PostFinance accepts a currency only when your own acquiring contract covers it. If a currency in the list above is not part of your contract, PostFinance rejects the payment rather than charging a different currency.
Supported Features
- Accept payments on PostFinance's hosted payment page, so card data never reaches your website
- Offer every payment method your PostFinance space has enabled, including cards, TWINT, PostFinance Card and e-finance
- Charge in ten currencies, subject to your acquiring contract
- Capture payments automatically at authorization
- Issue full refunds on completed payments
- Issue partial refunds, including several partial refunds against the same payment
- Pick up refunds you perform in the PostFinance dashboard, so your store's orders stay correct either way
- Receive real-time payment notifications signed with public-key cryptography
- Separate test and production spaces, each with its own credentials
PostFinance Checkout on PayLexer supports one-time payments and refunds. Recurring subscription billing is not available for this gateway, because PostFinance sells its subscription engine as a paid add-on that not all spaces have.
Before You Start
Make sure you have:
- PostFinance Checkout Account - Don't have one? Sign up for PostFinance Checkout →
- PayLexer Account - Required to configure the integration. Create your account →
- A website where you want to integrate
Looking for a different payment processor? View all supported gateways →
Configuring PostFinance Checkout
You need a Space ID, an Application User ID and an Authentication Key from PostFinance for this integration. All three come from different places in the PostFinance dashboard and are easy to confuse, so PayLexer labels each field the way PostFinance's own dashboard does.
The Authentication Key is shown exactly once when you create the application user. If you close the dialog without copying it, you cannot retrieve it - you have to create a new application user. This is the most common PostFinance setup dead end.
Getting API Credentials
Log in to the PostFinance Checkout dashboard
Sign in at checkout.postfinance.ch. Test and production are separate spaces on the same site, not separate URLs - make sure you are configuring the right space.
Copy your Space ID
Select the space you want to connect (test or production). The Space ID is displayed in the dashboard header and in the space's settings. It is a numeric identifier.
Create an Application User
Navigate to Account, then Users then Application Users and click Create Application User. Give it a recognizable name (e.g. "PayLexer").
Copy the Application User ID
After creating the user, copy its numeric Application User ID from the user list.
Copy the Authentication Key immediately
When the application user is created, PostFinance displays the Authentication Key in a dialog. Copy it now and store it securely.
This is your only chance to see the Authentication Key. Once you close this dialog, PostFinance will never show it again. If you lose it, you must create a new application user.
Grant the required permissions
Space → Settings → Webhook Listeners → Webhook URL → Create and Webhook Listener → Create - to receive payment notifications
A read-only role will pass the initial connection test but fail on every real payment.
The connection test in PayLexer checks for these permissions specifically. If your application user is too restricted, the test will fail and name the missing permission rather than letting you discover the problem at your first sale.
Adding Credentials to PayLexer
Open PayLexer Dashboard
Log in to your PayLexer dashboard and navigate to Payment Gateways → PostFinance Checkout.
Enter your credentials
Paste the Space ID, Application User ID and Authentication Key you copied from PostFinance into the corresponding fields.
Understanding Live/Production and Sandbox Settings:
| Environment | Purpose |
|---|---|
| Live / Production | Used for real transactions. |
| Test / Sandbox | Used for testing only. No real money is processed. |
How PayLexer selects credentials:
- Debug/Test mode ON → Test credentials are used
- Debug/Test mode OFF → Live credentials are used
Your test space and production space have different Space IDs and different Application Users. Entering a production Space ID with test credentials produces an authentication error.
Test and save
Click Save to save your configuration and verify your credentials. Click Verify Connection to test the connection.
The connection test checks both authentication and permissions. If your application user is read-only, the test fails and names the permission to grant.
Configuring Webhooks (Mandatory)
Webhooks enable real-time payment updates and significantly improve reliability.
Benefits of Webhooks:
- Instant payment status updates
- Automatic refund processing
- Dispute notifications
PayLexer registers its own notification address with your PostFinance space automatically on the first payment. There is no webhook URL to copy and no secret to paste - PostFinance signs each notification with its own key and publishes the matching public half, which PayLexer fetches to verify. This all happens without any dashboard steps on your part.
Unlike most gateways, there is no "webhook secret" field to configure. PostFinance uses public-key cryptography (ECDSA) rather than a shared secret, so PayLexer can verify notifications without you copying anything.
Your application user must have Webhook URL → Create and Webhook Listener → Create permissions for PayLexer to register its notification address. Without these, payments still work but status updates arrive only when the shopper returns to your site rather than in real time.
Integrate PostFinance Checkout to Your Website
If you have already added and configured your site, you can enable PostFinance Checkout in your existing setup.
Go to Websites
Navigate to Websites in your PayLexer dashboard.
Edit your website
Click the Edit Icon of your added website.
Enable PostFinance Checkout
Click the checkbox to enable PostFinance Checkout for the website.
If you haven't added a website yet, Continue to Add Your Website →
Troubleshooting
Best Practices
- Test in sandbox before enabling production so you can validate payments and refunds without moving real money.
- Copy the Authentication Key the moment PostFinance shows it. There is no way to retrieve it later.
- Grant your application user the minimum permissions it needs, but never less than what payments and refunds require.
- Enter both Test and Live credentials so you can switch safely between testing and production.
- Confirm your space has connector configurations for Visa and Mastercard before launch, or those card brands will be refused.
- Confirm with PostFinance that your acquiring contract covers every currency your website charges in.
- Enable TWINT and PostFinance Card/e-finance before launch if you sell to Swiss shoppers - a shopper who cannot pay with these often does not pay at all.
- Reconcile PayLexer orders against your PostFinance dashboard regularly.
FAQs
Still Have Questions?
- PostFinance Checkout Support: PostFinance Checkout Support
- PayLexer Support: Contact Support