Getting Started

Accept NFC payments from your own merchant app using the MONEI Pay SDKs.

How It Works

1. Your backend generates a POS auth token using your MONEI API key
2. Your merchant app receives the token via your own API
3. The app calls acceptPayment() with the token and amount
4. The SDK opens MONEI Pay (or CloudCommerce on Android) for NFC tap-to-pay
5. The payment result is returned to your app

:::note iOS Beta MONEI Pay for iOS is in beta. Join via TestFlight: https://testflight.apple.com/join/kZU2j445 :::

Download MONEI Pay

Step 1: Get Your API Key

1. Sign up at dashboard.monei.com
2. Go to Settings → API Keys
3. Use the test key for development, live key for production

Step 2: Generate a POS Auth Token

Your backend calls the MONEI API to create a token for each payment session. The token is valid for 24 hours — you can reuse it for multiple transactions within that window. Never expose your API key in the merchant app. See the full Create POS Auth Token API reference.

cURL

curl -X POST https://api.monei.com/v1/pos/auth-token \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
# Optional: include pointOfSaleId to associate payments with a specific terminal
# -d '{"pointOfSaleId": "pos_abc123"}'

Node.js

server.js

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

const monei = new Monei('YOUR_API_KEY');

const {token} = await monei.posAuthToken.create({
  // pointOfSaleId: 'pos_abc123', // optional
  // storeId: 'store_xyz',        // optional
});
// Send `token` to your merchant app

Python

server.py

import Monei

monei = Monei.MoneiClient(api_key="YOUR_API_KEY")

result = monei.pos_auth_token.create(
    # point_of_sale_id="pos_abc123",  # optional
    # store_id="store_xyz",           # optional
)
token = result.token
# Send `token` to your merchant app

PHP

server.php

<?php
require_once 'vendor/autoload.php';

use Monei\Model\CreatePosAuthTokenRequest;
use Monei\MoneiClient;

$monei = new MoneiClient('YOUR_API_KEY');

$result = $monei->posAuthToken->create(
  new CreatePosAuthTokenRequest([
    // 'point_of_sale_id' => 'pos_abc123', // optional
    // 'store_id' => 'store_xyz',          // optional
  ])
);
$token = $result->getToken();
// Send $token to your merchant app
?>

Request Parameters

Parameter	Type	Required	Description
pointOfSaleId	String	No	A unique identifier of the Point of Sale. If specified the payment is attached to this Point of Sale.
storeId	String	No	A unique identifier of the Store. If specified the payment is attached to this Store.

Response

{
  "token": "eyJhbGciOiJSUzI1NiIs..."
}

The token is a JWT (RS256-signed) containing the account ID and merchant metadata. It expires after 24 hours. Generate one per session — you don't need a new token for each transaction.

Step 3: Integrate Your App

Install the SDK, configure your project, call acceptPayment() with the token from Step 2, and handle results. Each guide covers installation, platform setup, SDK reference, example app, and troubleshooting.

• iOS — Swift SDK via SPM or CocoaPods
• Android — Kotlin SDK via GitHub Packages or JitPack, Direct vs Via MONEI Pay modes
• React Native — Expo module, cross-platform with one API

Verify Payments Server-Side

The SDK returns a PaymentResult to your app, but you should always verify the payment from your backend before fulfilling an order. This prevents client-side tampering.

Use the Get Payment endpoint with the transactionId returned in the result:

curl https://api.monei.com/v1/payments/{transactionId} \
  -H "Authorization: YOUR_API_KEY"

Alternatively, configure a callbackUrl when creating payments to receive asynchronous webhook notifications. See Verify signature for details on validating webhook payloads.

Common Issues

Problem	Cause	Solution
SDK returns "app not found"	MONEI Pay (or CloudCommerce on Android Direct mode) is not installed	Install the required app on the device
Token rejected / 401	Token expired (>24h) or wrong API key environment	Generate a fresh token; ensure test key for test mode, live key for production
NFC not working	NFC disabled or device unsupported	Check device settings; see MONEI Pay overview for device requirements
Payment succeeds on device but backend shows no record	Missing server-side verification	Always verify via API or webhooks (see above)

Next Steps

• MONEI Pay overview — product features and device requirements
• MONEI REST API — full API reference
• Testing — test cards and sandbox environment
• Verify signature — validate webhook payloads