Barion and SimplePay payments

Barion & SimplePay Integration

Hungarian payment gateways (Barion and OTP SimplePay) have specific protocol requirements around callbacks vs. browser redirects, signature verification, currency formatting and card-on-file recurring token consent.

1. Barion Smart Gateway (/v2/Payment/Start & /v2/Payment/GetPaymentState)

• Starting a payment (/v2/Payment/Start):
  • Send POSKey (server-side secret only), PaymentType: "Immediate" (or "Reservation"), PaymentWindow, GuestCheckOut: true, FundingSources: ["All"], PaymentRequestId (your internal unique payment attempt ID), RedirectUrl (browser return URL) and CallbackUrl (server-to-server webhook URL).
  • Include accurate item breakdowns (Items array with Name, Description, Quantity, Unit, UnitPrice, ItemTotal) matching the transaction Total.
• Barion Callback (Webhook) Pattern:
  • Barion's CallbackUrl receives only a lightweight notification (paymentId query/form parameter) indicating that the payment state changed.
  • Mandatory verification: on receiving the callback (or when the user returns to RedirectUrl), your server must call GET /v2/Payment/GetPaymentState?POSKey=...&PaymentId=... to fetch the authoritative Status (Prepared, Started, InProgress, Succeeded, Canceled, Expired, Failed).
  • Grant entitlements only when GetPaymentState returns Status === "Succeeded" and PaymentRequestId matches your internal order.
• Recurring / Tokenized Payments in Barion:
  • For subscriptions or one-click payments, pass InitiateRecurrence: true and a unique RecurrenceId on the initial citizen-present payment (with explicit user consent in the UI), then use RecurrenceType: "RecurringPayment" (or "MerchantInitiatedPayment") with trace IDs on subsequent charges.

2. OTP SimplePay v2 (/v2/start, IPN & /v2/query)

• HMAC-SHA384 Signature on Every Message:
  • SimplePay signs every JSON request and response using HMAC-SHA384 with your merchant secret key (per currency merchant account: HUF, EUR, USD often have separate merchant IDs and secret keys!).
  • Compute and verify the base64-encoded HMAC-SHA384 Signature header against the exact raw JSON body string before parsing.
• IPN (Instant Payment Notification) vs. back Redirect:
  • Browser return (back URL r parameter) is Base64-encoded JSON for displaying UI status only — never fulfill orders solely from back!
  • IPN Handler: when SimplePay POSTs to your IPN endpoint (status: "FINISHED"), verify the Signature header, add a receiveDate ISO timestamp to the JSON payload, sign the response body with HMAC-SHA384 in the response Signature header, and return HTTP 200.
  • Active Query (/v2/query): if IPN is delayed or browser return arrives first, call /v2/query with orderRef / transactionId to check authoritative status (FINISHED, TIMEOUT, CANCEL, FAIL).

3. Hungarian Market & Regulatory Requirements

• Mandatory Customer Transparency: both Barion and SimplePay onboarding/audit checklists require displaying the official payment provider logo/information banner, clear terms of service, recurring billing terms (if applicable) and accurate transaction failure details (transactionId shown to the user on failed payment).
• Currency & Decimals: for HUF, send whole integer amounts (unless specific decimal item pricing is required), and verify that sum of line items equals transaction total.