Stripe: setup and key permissions
Which Stripe key to enter in POSitive and which permissions to turn on for taking payments, the payouts report and refunds to the guest's card.
POSitive works with your Stripe account through a key you create yourself. The key's permissions decide what is available: taking payments, the payouts report and refunds to the guest's card.
Step 1. Create a key in Stripe
- Open the Stripe dashboard → Developers → API keys.
- Click Create restricted key and name it, for example “POSitive”.
- Turn on the permissions from the table below.
- Click Create and copy the key. It starts with
rk_live_.
Step 2. Turn on the permissions
Turn on every row at once, so you don't have to return to the Stripe dashboard for each feature.
| What it is for | Permission in Stripe | Level |
|---|---|---|
| Taking payments: card payment link | Checkout Sessions | Write |
| Taking payments: bank QR (PromptPay) | PaymentIntents | Write |
| Viewing: balance and money in processing | Balance | Read |
| Viewing: payouts to the bank | Payouts | Read |
| Viewing: which payments make up a payout, guest's card | Balance transaction sources | Read |
| Viewing: warnings about payment disputes | Disputes | Read |
| Viewing: payout schedule and warnings about stopped payouts | Connect → Accounts | Read |
| Refund to the guest's card | Charges and Refunds | Write |
Refunds also need PaymentIntents and Checkout Sessions, but the payment rows already turn those on.
In the Stripe dashboard open the “⋯” menu next to the key → Edit and add the permissions. The key value stays the same, so you don't need to enter it in POSitive again.
Don't forward it in messengers or keep it in notes. If the key may have reached someone else, delete it in the Stripe dashboard and create a new one. The Publishable key (pk_live_) will not work. A full Secret key (sk_live_) works, but it has every permission, so a restricted key is better.
Step 3. Enter the key in POSitive
- In the back office choose the venue and open Settings → Money.
- In the “Payment link — from chat and from the till” block turn on Allow payment links.
- Paste the key into Stripe secret key. The currency for Thailand is
thb. - Choose the payment methods the till will record the money with: one for card and one for bank QR.
- Click Save. A saved key is shown as dots.
The key is entered for each venue separately. If two venues share one key, their money arrives in one bank account.
For bank QR, turn on PromptPay in the Stripe dashboard: Settings → Payment methods.
Where to see the money
The report is in Money → Stripe: what is on its way to the bank, what is ready for payout, what is in processing and which payments make up each payout. Anyone with access to finances can open it.
How to refund to the guest's card
A refund needs the role permission for refunding and cancelling receipts in the back office, plus an authenticator app. You connect it once: profile menu at the top right → Authenticator → scan the QR code with an app such as Google Authenticator.
- Open Money → Receipts and click the receipt.
- On the receipt card click Refund.
- Choose the items and enter the reason.
- Tick Refund the guest to their card through Stripe.
- Enter the 6 digits from the app and confirm.
The money goes out right away and the refund is recorded on the receipt. It usually reaches the guest's card in 5–10 days. One code confirms only one action.
Only a receipt paid with a Stripe link from the till can be refunded to the card from POSitive:
- if part of the receipt was paid in cash or another way, make a regular refund and return the money yourself;
- orders paid on the website are refunded in the Stripe dashboard;
- don’t use this option for a receipt paid by bank QR (PromptPay). Stripe asks the guest for bank details by email, and a QR on the till is created without the guest’s email. Transfer the money to the guest yourself and make a regular refund.
If something doesn't work
| What you see | What to do |
|---|---|
| Money → Stripe lists permissions | Add those permissions to the key in the Stripe dashboard |
| The refund window says the key lacks permissions | Add Charges and Refunds — Write |
| Stripe did not accept the key | Check that the whole key was pasted and that it wasn't deleted in the Stripe dashboard |
| No “Refund” button | The receipt is still open, fully refunded, a test one or from another venue, or the role lacks the permission |
| No “refund to card” tick | The receipt wasn't paid with a Stripe link from the till |
| Bank QR isn't created | Check PaymentIntents — Write, that PromptPay is on, and the currency thb |