Create tokens on your server

The app needs a to accept payments. Your server gets the token from the MONEI API with your API key, and sends the token to the app.

Never put the API key in the app

The API key stays on your server. Anybody who extracts an API key from an app can use your MONEI account. The app gets only the token.

Request a token

Call Create POS Auth Token from your server:

cURL

curl -X POST https://api.monei.com/v1/pos/auth-token \
  -H "Authorization: $MONEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"storeId": "<MONEI store ID>"}'

Node.js

server.js

import {Monei} from '@monei-js/node-sdk';

const monei = new Monei(process.env.MONEI_API_KEY);

const {token} = await monei.posAuthToken.create({storeId: '<MONEI store ID>'});
// Send only `token` to the app.

Response:

{"token": "<jwt>"}

Send only the value of the token field to the app. Do not send the full JSON body. The SDK cannot use it.

Protect the endpoint that gives tokens to your app with your own authentication, so that only your devices get tokens.

Body fields

Both fields are optional.

Field	Value
storeId	The MONEI ID of the store where the device is. MONEI records the payments under this store. The store must belong to the account of the API key. If not, payments fail with "Store not found".
pointOfSaleId	The ID of a point of sale that you created in MONEI. Never use a device identifier here. If you do not send storeId, the store comes from the point of sale.

You find the store ID in MONEI Dashboard > Settings > Stores. See Stores and points of sale.

Token rules

• One token for each device. Cache the token for each device. Never get a new token for each payment.
• One account for each token. A token belongs to the account of the API key that created it. All payments with the token go to that account.
• Renew before expiry. A token is valid for 24 hours. Get a new token before it expires. Then call prepare again in the app with the new token. See Prepare the reader.
• Several MONEI accounts. If you have more than one MONEI account (for example, separate legal entities), each device uses the API key of the account that its store belongs to. Use one account on each device. MONEI has not yet tested a change to a different account on one device.
• Test and live. A test mode API key gives a sandbox token. A live API key gives a live token. Do not use test and live tokens on the same device. See Test mode.

Token lifecycle

1. On launch, the app asks your server for the token of the device.
2. Your server returns the cached token, or gets a new one from MONEI.
3. The app calls prepare with the token. The SDK keeps the token in memory only, so call prepare after each launch.
4. Before the token expires, the app gets a new token.
5. The app calls prepare again with the new token.

If the token expires before the app renews it, prepare and acceptPayment throw tokenExpired. No payment occurs. Get a new token, call prepare, and try again.

Common questions

Can I use one token on several devices?

No. Use one token for each device, and cache it for that device.

Why do payments fail with "Store not found"?

The storeId in the token request does not belong to the account of the API key. Use a store of the same account, or use the API key of the account that the store belongs to.

Do I need a new token for each payment?

No. A token is valid for 24 hours, for all payments on that device. Renew it before it expires.