Webhooks

How miaPOS notifies your backend when a payment changes state. Signed, idempotent, retried with backoff.

Overview

The E-comm callback is the authoritative channel for payment results. The browser redirect after checkout is for UX only — never fulfil an order based on the redirect alone. When a payment reaches a terminal state (SUCCESS, FAILED, refunded), miaPOS POSTs a signed JSON body to the callbackUrl the merchant supplied on POST /ecomm/api/v1/pay.

Payload

POST https://your-shop.example/miapos/callback HTTP/1.1
Content-Type: application/json

{
  "result": {
    "terminalId":     "123456",
    "orderId":        "order123",
    "paymentId":      "bc340d13-7411-4785-a083-b594b1384eb5",
    "status":         "SUCCESS",
    "amount":         145.25,
    "currency":       "MDL",
    "paymentDate":    "2024-05-20T16:32:28+03:00",
    "swiftMessageId": "swift123",
    "swiftPayerBank": "SomeBank"
  },
  "signature": "base64_encoded_signature"
}

The body has exactly two top-level fields — result and signature. The signature is transported inside the JSON body, not in a custom HTTP header.

Verify the signature

Every callback is signed with miaPOS' private key. Verify before trusting the payload — anyone can POST to your callbackUrl, and the signature is the only proof the payload came from miaPOS. Do not rely on IP allow-listing.

1. Parse the JSON. Extract result and signature.
2. Sort the keys of result alphabetically; concatenate the values with ;.
3. Base64-decode signature. Verify with SHA256withRSA (RSASSA-PKCS1-v1_5) using the miaPOS public key from GET /api/v1/public-key.

Full algorithm, canonical string example and Java / Python / PHP / Node.js reference implementations: Signature verification.

Response & retries

Return 2xx to acknowledge. Non-2xx responses and timeouts are retried by the E-comm service. Callbacks are effectively at-least-once — the same terminal state may be delivered more than once, so make the handler idempotent (short-circuit on repeat paymentId in a terminal state you have already processed).

Terminal statuses

The result.status field carries the payment outcome:

• SUCCESS — payment authorised and settled by the payer's bank
• FAILED — declined or aborted
• refunded — delivered after a refund is processed for a prior SUCCESS

See the E-comm Redoc reference for the full field schema of result.