Outbound Host API
The Outbound Host API lets the MineSec Access Gateway send payments to your host in one standard JSON format. You build a single adapter on your side that receives these messages and forwards them to your acquirer, processor or wallet platform. You do not need MineSec to build a dedicated integration for your host.
It covers both card payments (tap, chip, swipe) and QR payments (merchant-presented and consumer-presented codes).
Where it fits
The Host API is the call from MineSec to your host, shown in color below. Everything inside MineSec is run by MineSec; you build and run everything inside Your side.
- The SoftPOS App or Embedded Payment SDK captures the card or QR payment. Card data is encrypted on the device.
- The Access Gateway decrypts and validates the request, selects your host from the profile and acceptance you created, and builds a standard Host API message.
- The gateway calls your adapter over HTTPS. QR requests always carry your credential and an HMAC signature; card requests do when signing is enabled for your account.
- Your adapter translates the message into your host's protocol and returns the result in the standard response format.
Your host stays the system of authorization and settlement. MineSec handles the device, card reading, cryptography and transaction state.
Card and QR at a glance
| Card payments | QR payments | |
|---|---|---|
| Payment methods | Visa, Mastercard, UnionPay, Amex, JCB, Discover and more | Alipay, WeChat Pay, scheme QR, national QR schemes, unified QR |
| Endpoints you build | /transactions, /settlements, /batch-uploads, /sign-ons, /sign-offs | /qr-payments, /qr-payments/inquiries, /qr-payments/cancellations, /qr-payments/refunds |
| Outcome field | respCode (00 = approved) | status (SUCCESS, FAILED, ...) |
| Timeout recovery | MineSec sends a reversal | MineSec inquires, then cancels |
| Settlement | Batch totals, when host settlement is enabled | Host-captured; no batch messages |
| Guide | Card Payments | QR Payments |
A host can support card only, QR only, or both. A QR-only host does not need to implement the card endpoints, and the other way round.
What you build
| Item | Required for |
|---|---|
| HTTPS endpoint (base URL) | Card and QR |
| Request authentication (bearer credential) and HMAC signature check | QR always; card when enabled for your account |
| Idempotent handling of repeated requests | Card and QR |
| Card endpoints | Card |
| QR endpoints | QR |
| QR notify sender | Optional; speeds up QR result delivery |
| PIN and Track2 decryption under your keys | Card, when PIN or Track2 is sent to your host |
Integration journey
See Configuration & Go-live for each step.
The full API specification file and test environment details are shared with your team during onboarding. Contact your MineSec account manager to request them.
Terms
| Term | Meaning |
|---|---|
| Access Gateway | MineSec's payment gateway. It receives payments from devices, builds Host API messages and calls your adapter. |
Profile (profileId) | A merchant at MineSec: name, address, MCC, country and currency. Devices send payments against a profile. |
Acceptance (acptId) | The routing entry of a profile for one host: message format STD_JSON, payment methods, MID, TID and extraParams. |
| Acceptance tag | A label on an acceptance. Needed only when two acceptances of one profile support the same payment method: the payment request then names the tag (preferredAcceptanceTag) to pick one. |
PBO (pboId) | Payment Business Owner: your account at MineSec. |
ISV (isvId) | Independent software vendor: a partner that runs merchants on your account, set on the profile when used. |
enbrTranId | MineSec's ID for a transaction (tran_ + ULID). Reversals, voids and batch uploads keep the original's ID; a refund or a completion gets its own. |
enbrActionId | MineSec's ID for one operation on a QR payment, sent on cancellations. |
srsTranId | MineSec's order number for a transaction (for example M1866239185331064832), generated by MineSec. Use it with enbrTranId to look a transaction up with MineSec. |
sdkId | The SoftPOS App or Embedded Payment SDK installation that took the payment. |
trace | Per-message sequence number, like the system trace audit number of ISO 8583. |
Batch (batchId, batchNo) | A group of card transactions that is settled together. On QR requests, for reference only. |
posReference, extOrderId | References set by the POS application and by the merchant. |
| MPQR / CPQR | Merchant-presented QR (the customer scans the device) / consumer-presented QR (the device scans the customer's wallet). |