miaPOS.eu
Contact sales
Docs · Integration guides

E-commerce checkout

Integrate miaPOS as an instant-payment checkout in your online store. Token, register, callback, verify — four endpoints, signed responses.

AudienceDeveloper
DifficultyIntermediate
Updated2026-05-30

Overview

The miaPOS e-commerce protocol exposes a small REST surface that turns any web checkout into an instant-payment endpoint. The customer pays from their banking app via QR or Request to Pay; you receive a signed server-to-server callback with the final status.

Use this paypoint when you need to accept instant payments directly in a web flow without a hardware terminal. If you run on WooCommerce, OpenCart or CS-Cart, see the matching plugin instead — it implements this protocol for you.

Prerequisites

  • A miaPOS merchant account with at least one configured terminal.
  • Six credentials: merchantId, secretKey, terminalId, language, paymentType (qr or rtp), and ecommBaseUrl.
  • A publicly reachable HTTPS endpoint for callbacks.
  • The miaPOS public key for verifying signatures — see Signature verification.
Sandbox first
Start in ecomm-test.miapos.md. All four endpoints behave identically to production; payments are simulated. See Sandbox & environments.

Steps

1. Collect the order

Before initiating a payment, gather:

  • orderId — unique identifier generated by you
  • amount — decimal, e.g. 100.00
  • currency — ISO 4217, e.g. MDL
  • payDescription — human-readable, e.g. "Payment for Order #123"
  • clientName, clientPhone, clientEmail — optional

2. Obtain an access token

POST/ecomm/api/v1/token
curl -X POST https://ecomm-test.miapos.md/ecomm/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{"merchantId":"M12345","secretKey":"...","terminalId":"T0001"}'

3. Register the payment

POST/ecomm/api/v1/pay
{
  "orderId": "ORD-2026-00123",
  "amount": 100.00,
  "currency": "MDL",
  "payDescription": "Payment for Order #123",
  "language": "en",
  "paymentType": "qr",
  "successUrl": "https://shop.example.md/checkout/success",
  "failUrl":    "https://shop.example.md/checkout/fail",
  "callbackUrl":"https://shop.example.md/api/miapos/callback"
}

4. Handle the result

Customer is redirected to successUrl or failUrl. Independently, miaPOS POSTs the signed result to callbackUrl.

GET/ecomm/api/v1/payment/{paymentId}
Never trust redirects alone
The browser redirect can be spoofed or interrupted. Treat the signed callback as authoritative, and confirm with GET /payment/{paymentId} before fulfilling.

5. Verify the callback signature

GET/ecomm/api/v1/public-key

Full algorithm in Signature verification.

API summary

POST/ecomm/api/v1/token
POST/ecomm/api/v1/token/refresh
POST/ecomm/api/v1/pay
GET/ecomm/api/v1/payment/{paymentId}
GET/ecomm/api/v1/public-key

Complete request/response schemas in the E-comm API reference.

Errors

All error responses use a consistent envelope:

{
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Callback signature did not match the published public key.",
    "requestId": "req_01HZP2K7..."
  }
}

Catalog of common codes: INVALID_TOKEN, TOKEN_EXPIRED, INVALID_AMOUNT, UNKNOWN_PAYMENT, INVALID_SIGNATURE, RATE_LIMITED. Full list in Errors.

Examples & references

The integration repo on GitHub finergy-tech/mia-pay-ecomm-integration is the authoritative source for the protocol. It contains the protocol overview, signature-verification guide, and pointers to every official plugin and SDK.

Try it live — interactive demo at ecomm-test.miapos.md/demo-page.html. Enter your own success / fail / callback URLs and step through the full flow with the sandbox.

Ready-made plugins and SDKs — handle token / pay / callback / signature verification end-to-end:

Protocol details: