{ "openapi": "3.1.0", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "info": { "title": "MineSec Example Host API", "version": "0.0.1", "description": "## Introduction\n\n**SoftPOS <> MineSec Backend <> External Host**\n\nThis document describes the standard message format for communication between the MineSec Backend and an external host (your system).\n\n---\n\n## How It Works\n\nIn a typical SoftPOS transaction flow:\n\n1. **Card Data Capture:**\n - SoftPOS devices capture card data, and all sensitive information is encrypted.\n2. **Decryption & Translation:**\n - The encrypted data is sent to the MineSec Backend for decryption and translation.\n3. **Message Forwarding:**\n - The MineSec Backend forwards the payment message (e.g., in ISO8583 or JSON format) to the designated host using the format described in this document.\n\n**Note:** To receive messages from MineSec, you must create a profile with the message format `STD_JSON` via the [Profile Management API](https://glue-stage.mspayhub.com/swagger/profile).\n\n---\n\n## Configuration (via Profile Management API)\n\nRouting from the MineSec Backend is based on profiles that include configuration parameters such as MID and TID.\n\nTo set up a profile for the `STD_JSON` message format, define an **Acceptance** with the following parameters:\n\n| Config Param | Required | Description | Example |\n|------------------------|----------|----------------------------------------------------------------|--------------------------------------------------------------------|\n| `hostMessageFormat` | Yes | Expected value: `STD_JSON` | `STD_JSON` |\n| `supportedPayments` | Yes | Supported payment methods for routing | `[\"VISA\", \"MASTERCARD\"]` |\n| `primaryMid` | Yes | Primary Merchant ID (MID) | `123456789012345` |\n| `primaryTid` | Yes | Primary Terminal ID (TID) | `12345678` |\n| `subMid` | No | Optional sub MID | `sub_123` |\n| `subTid` | No | Optional sub TID | `sub_123` |\n| `extraParams.hostUrl` | Yes | Designated host URL; must be `https` (plain `http` is only allowed in local development) | `https://api.host.com/api/v1` |\n| `extraParams.hostAuth` | Depends | Value included in the authorization header. Required for QR acceptances. For card requests, only applied for accounts with request authentication enabled — check with the MineSec integration team whether this applies to your account. | `opaque-token` or a JWT |\n| `extraParams.hmacKey` | Depends | Shared HMAC key for message signing (hex encoded). Required for QR acceptances. For card requests, only applied for accounts with message signing enabled — check with the MineSec integration team whether this applies to your account. | `51637aaa1c6a4b1f0a48ff007cac09937f9cc6194570b054a32480f43535a22b` |\n| `extraParams.notifyProfile` | QR notify | How notifies from the host are signed and acknowledged. Issued by MineSec at onboarding; v1 has only `std-v1`. Without it the host gets no `notifyUrl` and MineSec relies on inquiries. | `std-v1` |\n| `extraParams.notifyKey` | QR notify | Hex-encoded HMAC key the host signs its notifies with. Issued by MineSec at onboarding; separate from `hmacKey`. | `bdc63a50c5c5740535ee8a5536ff51c47c986f88e54a8e299ca14f4b1ff29ce1` |\n| `extraParams.pinKey` | No | Hex-encoded double-length TDES key, used to translate the incoming PIN block into ISO format-0 (legacy `cardData.99` mode) | `e5d673084f40ad7c1cd520ecce734a23` |\n| `extraParams.pinDestKeyAlias` | No | Catalog alias of the dedicated PIN key. When set, the translated PIN block is sent in `pinBlock` and EMV tag 99 is omitted from `cardData`. | `host-api-example-pin-iso0` |\n| `extraParams.track2DestKeyAlias` | No | Catalog alias of the dedicated Track2 key. When set, encrypted Track2 is sent in `track2Data` and EMV tag 57 is omitted from `cardData`. | `host-api-example-track2` |\n| `extraParams.pinDestBlockFormat` | No | Optional override (`0`/`4`); defaults to the key algorithm (TDES → ISO-0, AES → ISO-4) and is rejected on mismatch. | `0` |\n\n### Example POST Request\n\nBelow is an example POST request to create a profile for the `STD_JSON` format. (This API call is made to the [Profile Management API](https://glue-stage.mspayhub.com/swagger/profile)):\n\n```http\nPOST {{baseUrl}}/api/v1/pos/profiles\nAuthorization: Bearer {{token}}\nContent-Type: application/json\n\n{\n \"profileName\": \"HostAPI-Example\",\n \"merchantName\": \"ACME\",\n \"merchantAddr\": \"No. 7, Park Avenue, Sunset Beach\",\n \"mcc\": \"5999\",\n \"countryCode\": \"HK\",\n \"currency\": \"HKD\",\n \"acceptances\": [\n {\n \"acptName\": \"Proc-Acpt\",\n \"acptReference\": \"proc-acpt-1\",\n \"hostMessageFormat\": \"STD_JSON\",\n \"supportedPayments\": [\n \"VISA\",\n \"MASTERCARD\"\n ],\n \"primaryMid\": \"111\",\n \"primaryTid\": \"222\",\n \"extraParams\": {\n \"hostUrl\": \"hostUrl-todo\",\n \"hostAuth\": \"hostAuth-todo\",\n \"hmacKey\": \"hmacKey-todo\",\n \"pinDestBlockFormat\": \"0\",\n \"pinDestKeyAlias\": \"host-api-example-pin-iso0-stage\",\n \"track2DestKeyAlias\": \"host-api-example-track2-stage\"\n }\n }\n ]\n}\n```\n\nThe profile will be used for routing, and the associated details (MID, TID, SubMid, SubTid) will be populated accordingly.\n\n---\n\n## Path Overview\n\nThe `STD_JSON` format expects the following endpoints from the host backend:\n\nNaming Convention:\n\n- Use lower kebab-case.\n- Endpoints should be plural.\n\n| route | usage |\n|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------|\n| `{hostUrl}/transactions` | For sale, refund, auth, auth completion, void, and reversal transactions. |\n| `{hostUrl}/settlements` | For settlement messages (first and trailer). |\n| `{hostUrl}/batch-uploads` | When initial settlements do not tally, a respCode: 95 is returned. The enabler resends each approved transaction for reconciliation. |\n| `{hostUrl}/sign-ons` | For sign-on operations. |\n| `{hostUrl}/sign-offs` | For sign-off operations. |\n\n---\n\n## Response\n\nAlways respond with HTTP `200` and a JSON payload. The MineSec Backend determines the outcome from the `respCode` in the response payload:\n\n- `\"respCode\": \"00\"` — the operation is successful.\n- Any other `respCode` — the operation is treated as declined or rejected.\n- A response that cannot be parsed as the expected JSON payload is treated as a failure.\n\nThis applies to all operations, including transactions, settlements, and sign-on requests.\n\n**Re-sign-on:** \nA transaction response may include `\"extra\": {\"requireSignOn\": \"true\"}`; the MineSec Backend will then perform a new sign-on before sending further requests for that acceptance.\n\n**Special Case – Settlement:** \nFor settlement operations, if the response payload contains a `respCode` of `\"95\"`, the MineSec Backend will trigger a batch upload process. This process re-sends all approved transactions in the batch for reconciliation.\n\n---\n\n## Timeout\n\nDefault timeout values for requests from the enabler are as follows:\n\n| timeout | value | will reversal trigger? |\n|------------|------------|------------------------|\n| connection | 3.seconds | No |\n| read/write | 30.seconds | Yes (new sale/refund/auth only) |\n\nNote: For new sale/refund/auth requests (`actionType: NEW`) to the `/transactions` endpoint, if a response is not received within the read/write timeout, reversal will be triggered immediately. Adjustment requests on the same endpoint (e.g. `VOID`, `AUTH_COMP`) are not automatically reversed on timeout.\n\n---\n\n## Common formatting\n\n### Currency & amount value\n\n- Currency is sent as ISO 4217 currency alpha-3 code, e.g. USD/ EUR/ HKD\n- Amount value is sent as decimal string with ISO decimal fraction, e.g. \"1.00\" for USD; \"1000\" for JPY\n\n### Timestamp\n\n- Timestamps are formatted in ISO8601 with an explicit offset, e.g. \"2025-02-11T02:37:57.311Z\"; transaction and settlement timestamps are in UTC\n- The timestamp represent the MineSec backend time instant\n\n### Extra\n\n- From certain request, there might be \"extra\" data that is pass-through from the POS/ POI request. e.g. `transactionRequest.posExtra`\n- 1 level struct, as a plain KV pair\n- Map\n- MineSec may also add `pinKsn` / `panKsn` entries to `posExtra` when the PIN block / Track2 carried in `cardData` are protected under DUKPT keys\n\n---\n\n## Request idempotency\n\nThe MineSec request (client) to this host API (server), in the request header there will be a `x-minesec-request-id`, with a ULID value.\n\nFrom your server side it is expected to check the uniqueness for this idempotency key to avoid duplicate handling of the same operation.\n\n```\nREQUEST: http://localhost:8080/api/v1/transactions\nMETHOD: HttpMethod(value=POST)\nCOMMON HEADERS\n-> Accept: application/json\n-> Accept-Charset: UTF-8\n-> Authorization: Bearer some-opaque-token\n-> x-minesec-request-id: 01JKF44HP0VYHTB0SNC0Y6VJQE\n...\n```\n\n---\n\n## Authorization\n\nQR requests (`/qr-payments`, `/qr-payments/inquiries`, `/qr-payments/cancellations`, `/qr-payments/refunds`) always include the `extraParams.hostAuth` value in the HTTP header. For card requests, the enabler includes it only for accounts with request authentication enabled. Whether this is enabled for your account depends on your integration configuration — confirm with the MineSec integration team.\n\nFor example, with the configuration below:\n\n```json\n{\n \"extraParams\": {\n \"hostUrl\": \"http://localhost:8080/api/v1\",\n \"hostAuth\": \"some-opaque-token\",\n \"hmacKey\": \"51637aaa1c6a4b1f0a48ff007cac09937f9cc6194570b054a32480f43535a22b\",\n \"pinDestBlockFormat\": \"0\",\n \"pinDestKeyAlias\": \"host-api-example-pin-iso0-stage\",\n \"track2DestKeyAlias\": \"host-api-example-track2-stage\"\n }\n}\n```\n\nA request from MineSec to the host API would look like:\n\n```\nREQUEST: http://localhost:8080/api/v1/transactions\nMETHOD: HttpMethod(value=POST)\nCOMMON HEADERS\n-> Accept: application/json\n-> Accept-Charset: UTF-8\n-> Authorization: Bearer some-opaque-token\n-> x-minesec-request-id: 01JKF44HP0VYHTB0SNC0Y6VJQE\n-> x-request-time: 2025-02-07T02:34:33Z\n-> x-signature: HmacSHA256 9f07909a151f50bb3280f955e4be659a4d081275428fa2bae6b9e07510056edb\nCONTENT HEADERS\n-> Content-Length: 1166\n-> Content-Type: application/json\nBODY Content-Type: application/json\nBODY START\n{\n \"enbrTranId\": \"tran_01JKF44JBWRNH1AG0GMMKA1M1B\",\n \"trace\": \"044883\",\n \"posReference\": \"4cea38d1-2d78-4833-8cef-4980b9406d94\",\n \"primaryMid\": \"111\",\n \"primaryTid\": \"222\",\n \"profileId\": \"prof_01JDK7CS51N7DM47JK9M4R9XPP\",\n \"acptId\": \"acpt_01JDK7CS6QKRN5K9BP053H0WBP\",\n \"tranType\": \"SALE\",\n \"actionType\": \"NEW\",\n \"isReversal\": false,\n \"amountValue\": \"1.00\",\n \"currency\": \"HKD\",\n \"paymentMethod\": \"VISA\",\n \"cardData\": {\n \"5F28\": \"0840\",\n \"5F2A\": \"0702\",\n \"5F34\": \"01\",\n \"82\": \"0020\",\n \"84\": \"a0000000031010\",\n \"95\": \"0000000000\",\n \"9A\": \"240513\",\n \"9B\": \"0000\",\n \"9C\": \"00\",\n \"9F02\": \"000000000100\",\n \"9F03\": \"000000000000\",\n \"9F10\": \"1f220100a000000000564953414c335445535443415345000000000000000000\",\n \"9F1A\": \"0702\",\n \"9F26\": \"a7265f79058a97dc\",\n \"9F27\": \"80\",\n \"9F33\": \"0020c8\",\n \"9F34\": \"000000\",\n \"9F35\": \"21\",\n \"9F36\": \"0002\",\n \"9F37\": \"865f8a02\",\n \"9F6E\": \"20700080\"\n },\n \"entryMode\": \"NFC\",\n \"cvmPerformed\": \"PIN\",\n \"pinBlock\": {\n \"pinKsn\": \"FFFF0000000000100001\",\n \"data\": \"8617b4d7bfc185ce\"\n },\n \"track2Data\": {\n \"track2Ksn\": \"FFFF0000000000100002\",\n \"data\": \"a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718\",\n \"track2Length\": 38\n },\n \"merchantName\": \"ACME\",\n \"merchantAddress\": \"No. 7, Park Avenue, Sunset Beach\",\n \"mcc\": \"5999\",\n \"batchNo\": \"029290\",\n \"batchId\": \"batch_01JKF2QRZJFZ5BHF0SC0X9ZR5M\",\n \"timestamp\": \"2025-02-07T02:34:33.732Z\"\n}\nBODY END\n```\n\n---\n\n## Message Signing\n\nQR requests are always signed using HMAC-SHA256. Card requests are signed only for accounts with message signing enabled; otherwise no `x-signature`/`x-request-time` headers are sent. Whether this is enabled for your account depends on your integration configuration — confirm with the MineSec integration team. When enabled, the signature is constructed as follows:\n\n```\n{HTTP_METHOD}.{PATH}.{ISO_TIME}.{PAYLOAD_BODY}\n```\n\n- HTTP_METHOD: like `POST`\n- PATH: The URL path (e.g., `/api/v1/transactions`)\n- ISO_TIME: An ISO8601 UTC timestamp (to second precision, e.g., `2025-02-07T02:34:33Z`), also included in the `x-request-time` header\n- PAYLOAD_BODY: The json body\n\nNote: Each segment is separated by two dots (`..`).\n\nexample being:\n\n```\nPOST../api/v1/transactions..2025-02-07T02:34:33Z..{\"enbrTranId\":\"tran_01JKF44JBWRNH1AG0GMMKA1M1B\",\"trace\":\"044883\"...}\n```\n\n---\n\n## Pin block translation\n\nPin blocks are translated to ISO format-0 using the TDES pin key (`extraParams.pinKey`, provided as a hex-encoded key — no RSA wrapping).\n\nThis legacy mode places the translated PIN block back into `cardData.99`. Acceptances configured with `pinDestKeyAlias`/`track2DestKeyAlias` instead use the dedicated `pinBlock`/`track2Data` fields (keys resolved server-side by alias), and the corresponding EMV tags (99/57) are omitted from `cardData`.\n\n### Example\n\nGiven the following acceptance configuration:\n\n```json\n{\n \"extraParams\": {\n \"hostUrl\": \"http://localhost:8080/api/v1\",\n \"hostAuth\": \"some-opaque-token\",\n \"hmacKey\": \"51637aaa1c6a4b1f0a48ff007cac09937f9cc6194570b054a32480f43535a22b\",\n \"pinKey\": \"e5d673084f40ad7c1cd520ecce734a23\"\n }\n}\n```\n\nin request's payload:\n\n```\nrequest.cardData.57: 4176662220010034D311220111523358\nrequest.cardData.99: 8617b4d7bfc185ce\n```\n\nbased on the config & info:\n\n```\nepb(format0): 8617b4d7bfc185ce\npan : 4176662220010034\npek : e5d673084f40ad7c1cd520ecce734a23\npin : 1234\n```\n\n---\n\n## Track2 encryption\n\nWhen the acceptance sets `extraParams.track2DestKeyAlias`, Track2 is sent in `track2Data` instead of `cardData.57`, encrypted under that key with DUKPT data-encryption. Track2 has no static-key form — the key must be DUKPT-derived (e.g. a BDK).\n\nBefore encryption the plaintext is **zero-padded up to the cipher block size** (8 bytes for TDES, 16 for AES; nothing is appended when the length is already a multiple). The decrypted result can therefore be longer than the original Track2, so `track2Data.track2Length` carries the original length and lets you trim the padding.\n\n`track2Length` counts **hex characters, not bytes** — a 19-byte Track2 reports `38`.\n\n### Recovering Track2\n\n1. Derive the data key from `track2Data.track2Ksn` and decrypt `track2Data.data`.\n2. Hex-encode the plaintext.\n3. Keep the first `track2Length` characters; the remainder is padding.\n\n### Example\n\nA 19-byte Track2 sent under a TDES key, padded to 24 bytes:\n\n```\ntrack2 (plain) : 4176662220010034123D311220111523358000 (38 hex chars = 19 bytes)\npadded (8-byte) : 4176662220010034123D3112201115233580000000000000 (24 bytes, 5 zero bytes appended)\ntrack2Ksn : FFFF0000000000100002\ntrack2Length : 38\n```\n\nAfter decrypting you get `4176662220010034123D3112201115233580000000000000`; taking the first 38 characters returns the original `4176662220010034123D311220111523358000`.\n\n---\n\n## Installment\n\nInstallments are a capability of a sale: an installment sale is sent with `tranType: SALE` and an `installment` object, and a sale without one is a regular sale. The legacy `tranType: INSTALL` carries only a count through the legacy `installmentPlan` field and never an `installment` object, since installments are not a capability of INSTALL. Every other new request omits it. The object is populated from the plan MineSec resolved and validated for the merchant, so no plan configuration is needed on the host side. Internal plan attributes (plan id/name, limits, minimum amount) are never sent.\n\n- `REGULAR`: `revolving` is omitted.\n- `REVOLVING`: `revolving` splits the original `amountValue` (which is unchanged) into `initialPaymentAmount` and `remainingAmount`; `installmentCount` applies to `remainingAmount`.\n- Amounts are pre-validated and passed as-is — do not recalculate interest or amortization.\n\n### Example (REVOLVING)\n\n```json\n{\n \"tranType\": \"SALE\",\n \"actionType\": \"NEW\",\n \"amountValue\": \"1000.00\",\n \"currency\": \"HKD\",\n \"installment\": {\n \"installmentCount\": 6,\n \"interestModel\": \"NO_INTEREST\",\n \"installmentType\": \"REVOLVING\",\n \"externalPlanCode\": \"BNK06\",\n \"revolving\": {\n \"initialPaymentAmount\": { \"value\": \"100.00\", \"currency\": \"HKD\" },\n \"remainingAmount\": { \"value\": \"900.00\", \"currency\": \"HKD\" }\n }\n }\n}\n```\n\n---\n\n## QR payments\n\nQR payments have their own resource, `/qr-payments`. A QR host does not need to implement `/transactions`.\n\n| Direction | Route | Purpose | Host must implement |\n|-----------|-------|---------|---------------------|\n| MineSec → Host | `POST /qr-payments` | Create. `MPQR` returns the QR to display, `CPQR` charges the scanned code | Yes |\n| MineSec → Host | `POST /qr-payments/inquiries` | Status of a payment or a refund | Yes |\n| MineSec → Host | `POST /qr-payments/cancellations` | Close an unpaid order, or reverse a paid one | Yes for `CPQR` |\n| MineSec → Host | `POST /qr-payments/refunds` | Full or partial refund | Optional |\n| Host → MineSec | `POST {notifyUrl}` | Final result (see Webhooks) | Optional |\n\n- **Outcome**: only `status` decides the outcome. `respCode` is kept for diagnostics and must be `00` when `status` is `PENDING` or `SUCCESS`.\n- **Idempotency**: `enbrTranId` is the idempotency key on every QR endpoint.\n- **Timing**: `CPQR` create and refunds must answer a final `SUCCESS` or `FAILED` within 20 seconds. `MPQR` create answers `PENDING` with the QR at once.\n- **Notify**: send it to `notifyUrl` unchanged, signed with `notifyKey` (see Webhooks). Only sent when the request carries a `notifyUrl`.\n- **Failures**: a `FAILED` result carries a `failureCode` and a `respMessage`.\n- **References**: `rrn` is the host's own reference for the payment and exists from create time; return it in every response, `PENDING` included. A payment that succeeded without an `rrn` cannot be traced or refunded. The wallet's own transaction id, if different, goes in `extra.walletTransactionId`.\n- **Unified QR**: with `paymentMethod: UNIFIED_QR` the host identifies the wallet and must return the concrete `paymentMethod` on `SUCCESS`.\n - `MPQR`: `acceptedPaymentMethods`, when sent, limits the wallets in the code.\n - `CPQR`: the POS could not tell the wallet from the scanned code. If the merchant does not accept that wallet, answer `FAILED` with `UNSUPPORTED_WALLET`.\n- Null fields are omitted from requests.\n" }, "servers": [ { "url": "http://localhost:8080", "description": "LOCAL" } ], "paths": { "/api/v1/sign-ons": { "post": { "tags": [ "Managements" ], "summary": "Sign on", "description": "Sign on to host", "parameters": [], "requestBody": { "description": "Sign on request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonSignOnReq" }, "examples": { "Example": { "value": "{\"trace\":\"000001\",\"primaryMid\":\"123456789012345\",\"primaryTid\":\"12345678\",\"subMid\":null,\"subTid\":null,\"profileId\":\"prof_123\",\"acptId\":\"acpt_123\",\"timestamp\":\"2025-01-01T00:00:00Z\",\"sdkId\":\"sdk_123\"}" } } } }, "required": true }, "responses": { "200": { "description": "Sign on response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonSignOnResp" }, "examples": { "Example": { "value": "{\"respCode\":\"00\",\"respMessage\":\"OK\",\"hostReferenceId\":\"host-ref-id-1234567890\",\"extra\":null}" } } } } } }, "deprecated": false, "security": [ { "BearerAuth": [] } ] }, "parameters": [] }, "/api/v1/sign-offs": { "post": { "tags": [ "Managements" ], "summary": "Sign off", "description": "Sign off from host", "parameters": [], "requestBody": { "description": "Sign off request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonSignOffReq" }, "examples": { "Example": { "value": "{\"trace\":\"000001\",\"primaryMid\":\"123456789012345\",\"primaryTid\":\"12345678\",\"subMid\":null,\"subTid\":null,\"profileId\":\"prof_123\",\"acptId\":\"acpt_123\",\"timestamp\":\"2025-01-01T00:00:00Z\"}" } } } }, "required": true }, "responses": { "200": { "description": "Sign on response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonSignOffResp" }, "examples": { "Example": { "value": "{\"respCode\":\"00\",\"respMessage\":\"OK\"}" } } } } } }, "deprecated": false, "security": [ { "BearerAuth": [] } ] }, "parameters": [] }, "/api/v1/transactions": { "post": { "tags": [ "Transactions" ], "summary": "Process transaction", "description": "Process transaction and return result", "parameters": [], "requestBody": { "description": "Transaction request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonTranReq" }, "examples": { "Example (SALE)": { "value": "{\"enbrTranId\":\"tran_123\",\"trace\":\"000001\",\"posReference\":null,\"primaryMid\":\"123456789012345\",\"primaryTid\":\"12345678\",\"subMid\":null,\"subTid\":null,\"profileId\":\"prof_123\",\"acptId\":\"acpt_123\",\"sdkId\":\"sdk_123\",\"merchantDevice\":\"SOFTPOS\",\"tranType\":\"SALE\",\"actionType\":\"NEW\",\"isReversal\":false,\"amountValue\":\"1.00\",\"currency\":\"USD\",\"posExtra\":{\"extraKey\":\"extraValue\"},\"paymentMethod\":\"VISA\",\"cardData\":{\"57\":\"4761731000000027d311220119058101\",\"9F6E\":\"20700080\",\"9F1A\":\"0702\",\"9F27\":\"80\",\"9A\":\"240513\",\"9B\":\"0000\",\"9F36\":\"0002\",\"9C\":\"00\",\"9F03\":\"000000000000\",\"9F26\":\"a7265f79058a97dc\",\"9F37\":\"865f8a02\",\"5F34\":\"01\",\"4F\":\"a0000000031010\",\"9F35\":\"21\",\"9F02\":\"000000000100\",\"9F10\":\"1f220100a000000000564953414c335445535443415345000000000000000000\",\"9F33\":\"0020c8\",\"9F66\":\"22804080\",\"5F2A\":\"0702\",\"82\":\"0020\",\"95\":\"0000000000\",\"84\":\"a0000000031010\",\"50\":\"VISA CREDIT\",\"5F28\":\"0840\",\"9F34\":\"000000\"},\"entryMode\":\"NFC\",\"cvmPerformed\":\"NO_CVM\",\"consumerDevice\":\"Card\",\"merchantName\":\"ACME\",\"merchantAddress\":\"ADDR\",\"mcc\":\"5814\",\"linkedEnbrTranId\":null,\"orgTrace\":null,\"orgRrn\":null,\"orgApprovalCode\":null,\"batchNo\":\"000001\",\"batchId\":\"batch_123\",\"timestamp\":\"2025-01-01T00:00:00Z\"}" }, "Example (SALE VOID)": { "value": "{\"enbrTranId\":\"tran_123\",\"trace\":\"000002\",\"posReference\":null,\"primaryMid\":\"123456789012345\",\"primaryTid\":\"12345678\",\"subMid\":null,\"subTid\":null,\"profileId\":\"prof_123\",\"acptId\":\"acpt_123\",\"sdkId\":\"sdk_123\",\"merchantDevice\":\"SOFTPOS\",\"tranType\":\"SALE\",\"actionType\":\"VOID\",\"isReversal\":false,\"amountValue\":\"1.00\",\"currency\":\"USD\",\"posExtra\":{\"extraKey\":\"extraValue\"},\"paymentMethod\":\"VISA\",\"cardData\":{\"57\":\"4761731000000027d311220119058101\"},\"entryMode\":\"NFC\",\"cvmPerformed\":\"NO_CVM\",\"consumerDevice\":\"Card\",\"merchantName\":\"ACME\",\"merchantAddress\":\"ADDR\",\"mcc\":\"5814\",\"linkedEnbrTranId\":null,\"orgTrace\":\"000001\",\"orgRrn\":\"123456123456\",\"orgApprovalCode\":\"123456\",\"batchNo\":\"000001\",\"batchId\":\"batch_123\",\"timestamp\":\"2025-01-01T00:00:00Z\"}" }, "Example (SALE REVERSAL)": { "value": "{\"enbrTranId\":\"tran_123\",\"trace\":\"000002\",\"posReference\":null,\"primaryMid\":\"123456789012345\",\"primaryTid\":\"12345678\",\"subMid\":null,\"subTid\":null,\"profileId\":\"prof_123\",\"acptId\":\"acpt_123\",\"sdkId\":\"sdk_123\",\"merchantDevice\":\"SOFTPOS\",\"tranType\":\"SALE\",\"actionType\":\"NEW\",\"isReversal\":true,\"amountValue\":\"1.00\",\"currency\":\"USD\",\"posExtra\":{\"extraKey\":\"extraValue\"},\"paymentMethod\":\"VISA\",\"cardData\":{\"57\":\"4761731000000027d311220119058101\",\"9F6E\":\"20700080\",\"9F1A\":\"0702\",\"9F27\":\"80\",\"9A\":\"240513\",\"9B\":\"0000\",\"9F36\":\"0002\",\"9C\":\"00\",\"9F03\":\"000000000000\",\"9F26\":\"a7265f79058a97dc\",\"9F37\":\"865f8a02\",\"5F34\":\"01\",\"4F\":\"a0000000031010\",\"9F35\":\"21\",\"9F02\":\"000000000100\",\"9F10\":\"1f220100a000000000564953414c335445535443415345000000000000000000\",\"9F33\":\"0020c8\",\"9F66\":\"22804080\",\"5F2A\":\"0702\",\"82\":\"0020\",\"95\":\"0000000000\",\"84\":\"a0000000031010\",\"50\":\"VISA CREDIT\",\"5F28\":\"0840\",\"9F34\":\"000000\"},\"entryMode\":\"NFC\",\"cvmPerformed\":\"NO_CVM\",\"consumerDevice\":\"Card\",\"merchantName\":\"ACME\",\"merchantAddress\":\"ADDR\",\"mcc\":\"5814\",\"linkedEnbrTranId\":null,\"orgTrace\":null,\"orgRrn\":null,\"orgApprovalCode\":null,\"batchNo\":\"000001\",\"batchId\":\"batch_123\",\"timestamp\":\"2025-01-01T00:00:00Z\"}" }, "Example (AUTH)": { "value": "{\"enbrTranId\":\"tran_123\",\"trace\":\"000001\",\"posReference\":null,\"primaryMid\":\"123456789012345\",\"primaryTid\":\"12345678\",\"subMid\":null,\"subTid\":null,\"profileId\":\"prof_123\",\"acptId\":\"acpt_123\",\"sdkId\":\"sdk_123\",\"merchantDevice\":\"SOFTPOS\",\"tranType\":\"AUTH\",\"actionType\":\"NEW\",\"isReversal\":false,\"amountValue\":\"1.00\",\"currency\":\"USD\",\"posExtra\":{\"extraKey\":\"extraValue\"},\"paymentMethod\":\"VISA\",\"cardData\":{\"57\":\"4761731000000027d311220119058101\",\"9F6E\":\"20700080\",\"9F1A\":\"0702\",\"9F27\":\"80\",\"9A\":\"240513\",\"9B\":\"0000\",\"9F36\":\"0002\",\"9C\":\"00\",\"9F03\":\"000000000000\",\"9F26\":\"a7265f79058a97dc\",\"9F37\":\"865f8a02\",\"5F34\":\"01\",\"4F\":\"a0000000031010\",\"9F35\":\"21\",\"9F02\":\"000000000100\",\"9F10\":\"1f220100a000000000564953414c335445535443415345000000000000000000\",\"9F33\":\"0020c8\",\"9F66\":\"22804080\",\"5F2A\":\"0702\",\"82\":\"0020\",\"95\":\"0000000000\",\"84\":\"a0000000031010\",\"50\":\"VISA CREDIT\",\"5F28\":\"0840\",\"9F34\":\"000000\"},\"entryMode\":\"NFC\",\"cvmPerformed\":\"NO_CVM\",\"consumerDevice\":\"Card\",\"merchantName\":\"ACME\",\"merchantAddress\":\"ADDR\",\"mcc\":\"5814\",\"linkedEnbrTranId\":null,\"orgTrace\":null,\"orgRrn\":null,\"orgApprovalCode\":null,\"batchNo\":\"000001\",\"batchId\":\"batch_123\",\"timestamp\":\"2025-01-01T00:00:00Z\"}" }, "Example (AUTH_COMP)": { "value": "{\"enbrTranId\":\"tran_123\",\"trace\":\"000002\",\"posReference\":null,\"primaryMid\":\"123456789012345\",\"primaryTid\":\"12345678\",\"subMid\":null,\"subTid\":null,\"profileId\":\"prof_123\",\"acptId\":\"acpt_123\",\"sdkId\":\"sdk_123\",\"merchantDevice\":\"SOFTPOS\",\"tranType\":\"AUTH_COMP\",\"actionType\":\"AUTH_COMP\",\"isReversal\":false,\"amountValue\":\"1.00\",\"currency\":\"USD\",\"posExtra\":{\"extraKey\":\"extraValue\"},\"paymentMethod\":\"VISA\",\"cardData\":{\"57\":\"4761731000000027d311220119058101\"},\"entryMode\":\"NFC\",\"cvmPerformed\":\"NO_CVM\",\"consumerDevice\":\"Card\",\"merchantName\":\"ACME\",\"merchantAddress\":\"ADDR\",\"mcc\":\"5814\",\"linkedEnbrTranId\":null,\"orgTrace\":\"000001\",\"orgRrn\":\"123456123456\",\"orgApprovalCode\":\"123456\",\"batchNo\":\"000001\",\"batchId\":\"batch_123\",\"timestamp\":\"2025-01-01T00:00:00Z\"}" }, "Example (REFUND)": { "value": "{\"enbrTranId\":\"tran_123\",\"trace\":\"000001\",\"posReference\":null,\"primaryMid\":\"123456789012345\",\"primaryTid\":\"12345678\",\"subMid\":null,\"subTid\":null,\"profileId\":\"prof_123\",\"acptId\":\"acpt_123\",\"sdkId\":\"sdk_123\",\"merchantDevice\":\"SOFTPOS\",\"tranType\":\"REFUND\",\"actionType\":\"NEW\",\"isReversal\":false,\"amountValue\":\"1.00\",\"currency\":\"USD\",\"posExtra\":{\"extraKey\":\"extraValue\"},\"paymentMethod\":\"VISA\",\"cardData\":{\"57\":\"4761731000000027d311220119058101\",\"9F6E\":\"20700080\",\"9F1A\":\"0702\",\"9F27\":\"80\",\"9A\":\"240513\",\"9B\":\"0000\",\"9F36\":\"0002\",\"9C\":\"00\",\"9F03\":\"000000000000\",\"9F26\":\"a7265f79058a97dc\",\"9F37\":\"865f8a02\",\"5F34\":\"01\",\"4F\":\"a0000000031010\",\"9F35\":\"21\",\"9F02\":\"000000000100\",\"9F10\":\"1f220100a000000000564953414c335445535443415345000000000000000000\",\"9F33\":\"0020c8\",\"9F66\":\"22804080\",\"5F2A\":\"0702\",\"82\":\"0020\",\"95\":\"0000000000\",\"84\":\"a0000000031010\",\"50\":\"VISA CREDIT\",\"5F28\":\"0840\",\"9F34\":\"000000\"},\"entryMode\":\"NFC\",\"cvmPerformed\":\"NO_CVM\",\"consumerDevice\":\"Card\",\"merchantName\":\"ACME\",\"merchantAddress\":\"ADDR\",\"mcc\":\"5814\",\"linkedEnbrTranId\":null,\"orgTrace\":null,\"orgRrn\":null,\"orgApprovalCode\":null,\"batchNo\":\"000001\",\"batchId\":\"batch_123\",\"timestamp\":\"2025-01-01T00:00:00Z\"}" } } } }, "required": true }, "responses": { "200": { "description": "Transaction response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonTranResp" }, "examples": { "Example (APPROVED)": { "value": "{\"respCode\":\"00\",\"respMessage\":\"Approved\",\"hostReferenceId\":\"host-ref-id-1234567890\",\"rrn\":\"123456123456\",\"approvalCode\":\"123456\"}" }, "Example (DECLINED)": { "value": "{\"respCode\":\"05\",\"respMessage\":\"Do not honor\",\"hostReferenceId\":\"host-ref-id-1234567890\",\"rrn\":null,\"approvalCode\":null}" } } } } } }, "deprecated": false, "security": [ { "BearerAuth": [] } ] }, "parameters": [] }, "/api/v1/settlements": { "post": { "tags": [ "Settlements" ], "summary": "Process settlement", "description": "Process settlement and return result", "parameters": [], "requestBody": { "description": "Settlement request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonSettleReq" }, "examples": { "Example (First settlement)": { "value": "{\"trace\":\"000001\",\"batchId\":\"batch_123\",\"batchNo\":\"000001\",\"primaryMid\":\"123456789012345\",\"primaryTid\":\"12345678\",\"subMid\":null,\"subTid\":null,\"profileId\":\"prof_123\",\"acptId\":\"acpt_123\",\"isSecond\":false,\"summary\":[{\"tranType\":\"SALE\",\"tranStatus\":\"APPROVED\",\"count\":1,\"total\":{\"value\":\"1.00\",\"currency\":\"USD\"},\"paymentMethod\":null}],\"timestamp\":\"2025-01-01T00:00:00Z\"}" }, "Example (Second settlement after batch uploads)": { "value": "{\"trace\":\"000001\",\"batchId\":\"batch_123\",\"batchNo\":\"000001\",\"primaryMid\":\"123456789012345\",\"primaryTid\":\"12345678\",\"subMid\":null,\"subTid\":null,\"profileId\":\"prof_123\",\"acptId\":\"acpt_123\",\"isSecond\":true,\"summary\":[{\"tranType\":\"SALE\",\"tranStatus\":\"APPROVED\",\"count\":1,\"total\":{\"value\":\"1.00\",\"currency\":\"USD\"},\"paymentMethod\":null}],\"timestamp\":\"2025-01-01T00:00:00Z\"}" } } } }, "required": true }, "responses": { "200": { "description": "Settlement response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonSettleResp" }, "examples": { "Example (Settlement success)": { "value": "{\"respCode\":\"00\",\"respMessage\":\"Success\",\"hostReferenceId\":\"host-ref-id-1234567890\"}" }, "Example (Batch mismatch)": { "value": "{\"respCode\":\"95\",\"respMessage\":\"Batch mismatch\",\"hostReferenceId\":\"host-ref-id-1234567890\"}" } } } } } }, "deprecated": false, "security": [ { "BearerAuth": [] } ] }, "parameters": [] }, "/api/v1/batch-uploads": { "post": { "tags": [ "Settlements" ], "summary": "Process batch upload", "description": "Process batch upload and return result", "parameters": [], "requestBody": { "description": "Batch upload request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonTranReq" }, "examples": { "Example": { "value": "{\"enbrTranId\":\"tran_123\",\"trace\":\"000001\",\"posReference\":null,\"primaryMid\":\"123456789012345\",\"primaryTid\":\"12345678\",\"subMid\":null,\"subTid\":null,\"profileId\":\"prof_123\",\"acptId\":\"acpt_123\",\"sdkId\":\"sdk_123\",\"merchantDevice\":\"SOFTPOS\",\"tranType\":\"SALE\",\"actionType\":\"NEW\",\"isReversal\":false,\"amountValue\":\"1.00\",\"currency\":\"USD\",\"posExtra\":{\"extraKey\":\"extraValue\"},\"paymentMethod\":\"VISA\",\"cardData\":{\"57\":\"4761731000000027d311220119058101\",\"9F6E\":\"20700080\",\"9F1A\":\"0702\",\"9F27\":\"80\",\"9A\":\"240513\",\"9B\":\"0000\",\"9F36\":\"0002\",\"9C\":\"00\",\"9F03\":\"000000000000\",\"9F26\":\"a7265f79058a97dc\",\"9F37\":\"865f8a02\",\"5F34\":\"01\",\"4F\":\"a0000000031010\",\"9F35\":\"21\",\"9F02\":\"000000000100\",\"9F10\":\"1f220100a000000000564953414c335445535443415345000000000000000000\",\"9F33\":\"0020c8\",\"9F66\":\"22804080\",\"5F2A\":\"0702\",\"82\":\"0020\",\"95\":\"0000000000\",\"84\":\"a0000000031010\",\"50\":\"VISA CREDIT\",\"5F28\":\"0840\",\"9F34\":\"000000\"},\"entryMode\":\"NFC\",\"cvmPerformed\":\"NO_CVM\",\"consumerDevice\":\"Card\",\"merchantName\":\"ACME\",\"merchantAddress\":\"ADDR\",\"mcc\":\"5814\",\"linkedEnbrTranId\":null,\"orgTrace\":null,\"orgRrn\":null,\"orgApprovalCode\":null,\"batchNo\":\"000001\",\"batchId\":\"batch_123\",\"timestamp\":\"2025-01-01T00:00:00Z\"}" } } } }, "required": true }, "responses": { "200": { "description": "Batch upload response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonTranResp" }, "examples": { "Example": { "value": "{\"respCode\":\"00\",\"respMessage\":\"Success\",\"hostReferenceId\":null,\"rrn\":null,\"approvalCode\":null}" } } } } } }, "deprecated": false, "security": [ { "BearerAuth": [] } ] }, "parameters": [] }, "/api/v1/qr-payments": { "post": { "tags": [ "QR Payments" ], "summary": "Create QR payment", "description": "Creates a QR payment. `MPQR` answers `PENDING` with the `qrCode` to display. `CPQR` charges the scanned `consumerCode` and must answer a final `SUCCESS` or `FAILED` within 20 seconds. Without a final answer by then, MineSec sends a cancellation with reason `TIMEOUT`, and its result decides the payment.\n\n`enbrTranId` is the idempotency key: a repeated request must return the result of the first one and must not create a second order.", "parameters": [], "requestBody": { "description": "Create QR payment request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonQrPaymentReq" }, "examples": { "MPQR request, unified QR": { "value": { "enbrTranId": "tran_01JKF44JBWRNH1AG0GMMKA1M1B", "srsTranId": "SRS20261013000812", "trace": "044883", "posReference": "4cea38d1-2d78-4833-8cef-4980b9406d94", "extOrderId": "INV-2026-000812", "pboId": "pbo_01HZX3M0Q2", "isvId": "isv_778", "profileId": "prof_01JDK7CS51N7DM47JK9M4R9XPP", "providerMchId": "M-100233", "shopId": "S-0007", "shopName": "ACME Central", "acptId": "acpt_01JDK7CS6QKRN5K9BP053H0WBP", "primaryMid": "111", "primaryTid": "222", "subMid": "sub_123", "sdkId": "sdk_9f3c21", "operatorId": "cashier-04", "merchantDevice": "SOFTPOS", "qrMode": "MPQR", "tranType": "SALE", "amountValue": "128.00", "currency": "HKD", "paymentMethod": "UNIFIED_QR", "acceptedPaymentMethods": [ "ALIPAY", "WECHAT", "UNIONPAY_QR" ], "qrExpirySeconds": 300, "notifyUrl": "https://webhook.mspayhub.com/v1/payment/standard/std-v1/tran_01JKF44JBWRNH1AG0GMMKA1M1B", "merchantName": "ACME", "merchantAddress": "No. 7, Park Avenue, Sunset Beach", "merchantCity": "Hong Kong", "merchantCountry": "HK", "mcc": "5999", "terminalIp": "203.0.113.24", "batchId": "batch_01JKF2QRZJFZ5BHF0SC0X9ZR5M", "batchNo": "029290", "posExtra": { "tableNo": "12" }, "timestamp": "2026-10-13T08:10:33.732Z" } }, "CPQR request": { "value": { "enbrTranId": "tran_01JKF5B2M9T4W7X1C3E8R6Y0ZQ", "srsTranId": "SRS20261013000812", "trace": "044884", "posReference": "4cea38d1-2d78-4833-8cef-4980b9406d94", "extOrderId": "INV-2026-000812", "pboId": "pbo_01HZX3M0Q2", "isvId": "isv_778", "profileId": "prof_01JDK7CS51N7DM47JK9M4R9XPP", "providerMchId": "M-100233", "shopId": "S-0007", "shopName": "ACME Central", "acptId": "acpt_01JDK7CS6QKRN5K9BP053H0WBP", "primaryMid": "111", "primaryTid": "222", "subMid": "sub_123", "sdkId": "sdk_9f3c21", "operatorId": "cashier-04", "merchantDevice": "SOFTPOS", "qrMode": "CPQR", "tranType": "SALE", "amountValue": "128.00", "currency": "HKD", "paymentMethod": "WECHAT", "consumerCode": { "value": "134567890123456789", "format": "BARCODE_NUMERIC", "scanMethod": "CAMERA" }, "notifyUrl": "https://webhook.mspayhub.com/v1/payment/standard/std-v1/tran_01JKF5B2M9T4W7X1C3E8R6Y0ZQ", "merchantName": "ACME", "merchantAddress": "No. 7, Park Avenue, Sunset Beach", "merchantCity": "Hong Kong", "merchantCountry": "HK", "mcc": "5999", "terminalIp": "203.0.113.24", "batchId": "batch_01JKF2QRZJFZ5BHF0SC0X9ZR5M", "batchNo": "029290", "timestamp": "2026-10-13T08:15:38.104Z" } }, "CPQR request, unified QR": { "value": { "enbrTranId": "tran_01JKF5B2M9T4W7X1C3E8R6Y0ZQ", "srsTranId": "SRS20261013000812", "trace": "044884", "posReference": "4cea38d1-2d78-4833-8cef-4980b9406d94", "extOrderId": "INV-2026-000812", "pboId": "pbo_01HZX3M0Q2", "isvId": "isv_778", "profileId": "prof_01JDK7CS51N7DM47JK9M4R9XPP", "providerMchId": "M-100233", "shopId": "S-0007", "shopName": "ACME Central", "acptId": "acpt_01JDK7CS6QKRN5K9BP053H0WBP", "primaryMid": "111", "primaryTid": "222", "subMid": "sub_123", "sdkId": "sdk_9f3c21", "operatorId": "cashier-04", "merchantDevice": "SOFTPOS", "qrMode": "CPQR", "tranType": "SALE", "amountValue": "128.00", "currency": "HKD", "paymentMethod": "UNIFIED_QR", "consumerCode": { "value": "134567890123456789", "format": "BARCODE_NUMERIC", "scanMethod": "CAMERA" }, "notifyUrl": "https://webhook.mspayhub.com/v1/payment/standard/std-v1/tran_01JKF5B2M9T4W7X1C3E8R6Y0ZQ", "merchantName": "ACME", "merchantAddress": "No. 7, Park Avenue, Sunset Beach", "merchantCity": "Hong Kong", "merchantCountry": "HK", "mcc": "5999", "terminalIp": "203.0.113.24", "batchId": "batch_01JKF2QRZJFZ5BHF0SC0X9ZR5M", "batchNo": "029290", "timestamp": "2026-10-13T08:15:38.104Z" } } } } }, "required": true }, "responses": { "200": { "description": "Payment result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonQrResult" }, "examples": { "MPQR response": { "value": { "respCode": "00", "respMessage": "Accepted", "status": "PENDING", "enbrTranId": "tran_01JKF44JBWRNH1AG0GMMKA1M1B", "rrn": "H202610130000123", "paymentMethod": "UNIFIED_QR", "amountValue": "128.00", "currency": "HKD", "qrCode": { "content": "https://pay.host.example/q/8Hk2pQ7xLm", "format": "URL", "reference": "8Hk2pQ7xLm" }, "expiresAt": "2026-10-13T08:15:33Z" } }, "CPQR response, paid at once": { "value": { "respCode": "00", "respMessage": "Approved", "status": "SUCCESS", "enbrTranId": "tran_01JKF5B2M9T4W7X1C3E8R6Y0ZQ", "rrn": "H202610130000124", "networkMerchantId": "1900012345", "paymentMethod": "WECHAT", "amountValue": "128.00", "currency": "HKD", "paidAt": "2026-10-13T08:15:40Z", "payer": { "id": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o", "fundingSource": "BALANCE" }, "settlementDate": "2026-10-14", "extra": { "walletTransactionId": "4200002891202610135566778899" } } }, "Failed": { "value": { "respCode": "51", "respMessage": "Insufficient balance", "status": "FAILED", "failureCode": "INSUFFICIENT_FUNDS", "enbrTranId": "tran_01JKF5B2M9T4W7X1C3E8R6Y0ZQ", "rrn": "H202610130000124", "paymentMethod": "WECHAT", "amountValue": "128.00", "currency": "HKD" } } } } } } }, "deprecated": false, "security": [ { "BearerAuth": [] } ] }, "parameters": [] }, "/api/v1/qr-payments/inquiries": { "post": { "tags": [ "QR Payments" ], "summary": "Inquire QR payment or refund", "description": "Returns the current status of a payment or a refund. Mandatory for every QR host: MineSec polls it whether or not the host sends notifies.", "parameters": [], "requestBody": { "description": "Inquire QR payment or refund request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonQrInquiryReq" }, "examples": { "Payment inquiry": { "value": { "enbrTranId": "tran_01JKF44JBWRNH1AG0GMMKA1M1B", "srsTranId": "SRS20261013000812", "trace": "044885", "posReference": "4cea38d1-2d78-4833-8cef-4980b9406d94", "extOrderId": "INV-2026-000812", "pboId": "pbo_01HZX3M0Q2", "isvId": "isv_778", "profileId": "prof_01JDK7CS51N7DM47JK9M4R9XPP", "providerMchId": "M-100233", "shopId": "S-0007", "shopName": "ACME Central", "acptId": "acpt_01JDK7CS6QKRN5K9BP053H0WBP", "primaryMid": "111", "primaryTid": "222", "subMid": "sub_123", "sdkId": "sdk_9f3c21", "operatorId": "cashier-04", "inquiryType": "PAYMENT", "rrn": "H202610130000123", "timestamp": "2026-10-13T08:10:48.020Z" } }, "Refund inquiry": { "value": { "enbrTranId": "tran_01JKF9R1REFUND0000000000001", "srsTranId": "SRS20261013000812", "trace": "044888", "posReference": "4cea38d1-2d78-4833-8cef-4980b9406d94", "extOrderId": "INV-2026-000812", "pboId": "pbo_01HZX3M0Q2", "isvId": "isv_778", "profileId": "prof_01JDK7CS51N7DM47JK9M4R9XPP", "providerMchId": "M-100233", "shopId": "S-0007", "shopName": "ACME Central", "acptId": "acpt_01JDK7CS6QKRN5K9BP053H0WBP", "primaryMid": "111", "primaryTid": "222", "subMid": "sub_123", "sdkId": "sdk_9f3c21", "operatorId": "cashier-04", "inquiryType": "REFUND", "rrn": "R202610130000031", "timestamp": "2026-10-13T09:40:20.000Z" } } } } }, "required": true }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonQrResult" }, "examples": { "Paid": { "value": { "respCode": "00", "status": "SUCCESS", "enbrTranId": "tran_01JKF44JBWRNH1AG0GMMKA1M1B", "rrn": "H202610130000123", "networkMerchantId": "2088621900012345", "primaryMid": "111", "primaryTid": "222", "paymentMethod": "ALIPAY", "amountValue": "128.00", "currency": "HKD", "paidAt": "2026-10-13T08:12:05Z", "payer": { "id": "2088102112345678", "fundingSource": "CARD" }, "settlementDate": "2026-10-14", "extra": { "walletTransactionId": "2026101322001412345678901234" } } }, "Still pending": { "value": { "respCode": "00", "respMessage": "Waiting for payer", "status": "PENDING", "enbrTranId": "tran_01JKF5B2M9T4W7X1C3E8R6Y0ZQ", "rrn": "H202610130000124", "paymentMethod": "WECHAT", "amountValue": "128.00", "currency": "HKD" } }, "Refunded": { "value": { "respCode": "00", "status": "SUCCESS", "enbrTranId": "tran_01JKF9R1REFUND0000000000001", "linkedEnbrTranId": "tran_01JKF44JBWRNH1AG0GMMKA1M1B", "rrn": "R202610130000031", "orgRrn": "H202610130000123", "paymentMethod": "ALIPAY", "amountValue": "28.00", "currency": "HKD", "refundedAt": "2026-10-13T09:40:11Z", "refundedAmount": "28.00", "extra": { "walletTransactionId": "2026101322001412345678909999" } } } } } } } }, "deprecated": false, "security": [ { "BearerAuth": [] } ] }, "parameters": [] }, "/api/v1/qr-payments/cancellations": { "post": { "tags": [ "QR Payments" ], "summary": "Cancel QR payment", "description": "Closes an unpaid order, or reverses a paid or uncertain one. Mandatory for `CPQR`, recommended for `MPQR`.\n\nAnswer `CLOSED` if no money moved, `REVERSED` if the payer was charged and the money was returned, and `FAILED` if the payment could not be cancelled. After a `CPQR` timeout this result decides the transaction.\n\nMineSec may cancel a payment whose create request never reached the host. Answer `CLOSED` in that case; `rrn` is then omitted.", "parameters": [], "requestBody": { "description": "Cancel QR payment request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonQrCancellationReq" }, "examples": { "Cancellation after timeout": { "value": { "enbrTranId": "tran_01JKF5B2M9T4W7X1C3E8R6Y0ZQ", "enbrActionId": "act_01JKF5C8Y2N6Q4V9B7D1S3T5WX", "srsTranId": "SRS20261013000812", "trace": "044886", "posReference": "4cea38d1-2d78-4833-8cef-4980b9406d94", "extOrderId": "INV-2026-000812", "pboId": "pbo_01HZX3M0Q2", "isvId": "isv_778", "profileId": "prof_01JDK7CS51N7DM47JK9M4R9XPP", "providerMchId": "M-100233", "shopId": "S-0007", "shopName": "ACME Central", "acptId": "acpt_01JDK7CS6QKRN5K9BP053H0WBP", "primaryMid": "111", "primaryTid": "222", "subMid": "sub_123", "sdkId": "sdk_9f3c21", "operatorId": "cashier-04", "reason": "TIMEOUT", "rrn": "H202610130000124", "timestamp": "2026-10-13T08:16:40.512Z" } } } } }, "required": true }, "responses": { "200": { "description": "Cancellation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonQrResult" }, "examples": { "Closed, no money moved": { "value": { "respCode": "00", "respMessage": "Order closed", "status": "CLOSED", "enbrTranId": "tran_01JKF5B2M9T4W7X1C3E8R6Y0ZQ", "rrn": "H202610130000124", "paymentMethod": "WECHAT", "amountValue": "128.00", "currency": "HKD" } }, "Reversed": { "value": { "respCode": "00", "respMessage": "Payment reversed", "status": "REVERSED", "enbrTranId": "tran_01JKF5B2M9T4W7X1C3E8R6Y0ZQ", "rrn": "H202610130000124", "paymentMethod": "WECHAT", "amountValue": "128.00", "currency": "HKD", "extra": { "walletTransactionId": "4200002891202610135566778899" } } }, "Closed, order never reached the host": { "value": { "respCode": "00", "respMessage": "Order not found, nothing to cancel", "status": "CLOSED", "enbrTranId": "tran_01JKF5B2M9T4W7X1C3E8R6Y0ZQ", "amountValue": "128.00", "currency": "HKD" } } } } } } }, "deprecated": false, "security": [ { "BearerAuth": [] } ] }, "parameters": [] }, "/api/v1/qr-payments/refunds": { "post": { "tags": [ "QR Payments" ], "summary": "Refund QR payment", "description": "Refunds a paid payment, in full or in part. Optional. A refund is a transaction of its own, with its own `enbrTranId`; it does not change the status of the payment. Answer a final `SUCCESS` or `FAILED` within 20 seconds; do not answer `PENDING`. A refund without a final answer in time stays unresolved at MineSec until it is reconciled with the host, and is not sent again.", "parameters": [], "requestBody": { "description": "Refund QR payment request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonQrRefundReq" }, "examples": { "Partial refund": { "value": { "enbrTranId": "tran_01JKF9R1REFUND0000000000001", "srsTranId": "SRS20261013000812", "trace": "044887", "posReference": "4cea38d1-2d78-4833-8cef-4980b9406d94", "extOrderId": "INV-2026-000812", "pboId": "pbo_01HZX3M0Q2", "isvId": "isv_778", "profileId": "prof_01JDK7CS51N7DM47JK9M4R9XPP", "providerMchId": "M-100233", "shopId": "S-0007", "shopName": "ACME Central", "acptId": "acpt_01JDK7CS6QKRN5K9BP053H0WBP", "primaryMid": "111", "primaryTid": "222", "subMid": "sub_123", "sdkId": "sdk_9f3c21", "operatorId": "cashier-04", "amountValue": "28.00", "currency": "HKD", "reason": "Item returned", "notifyUrl": "https://webhook.mspayhub.com/v1/payment/standard/std-v1/tran_01JKF9R1REFUND0000000000001", "linkedEnbrTranId": "tran_01JKF44JBWRNH1AG0GMMKA1M1B", "orgRrn": "H202610130000123", "timestamp": "2026-10-13T09:40:08.310Z" } } } } }, "required": true }, "responses": { "200": { "description": "Refund result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonQrResult" }, "examples": { "Refunded": { "value": { "respCode": "00", "status": "SUCCESS", "enbrTranId": "tran_01JKF9R1REFUND0000000000001", "linkedEnbrTranId": "tran_01JKF44JBWRNH1AG0GMMKA1M1B", "rrn": "R202610130000031", "orgRrn": "H202610130000123", "paymentMethod": "ALIPAY", "amountValue": "28.00", "currency": "HKD", "refundedAt": "2026-10-13T09:40:11Z", "extra": { "walletTransactionId": "2026101322001412345678909999" } } } } } } } }, "deprecated": false, "security": [ { "BearerAuth": [] } ] }, "parameters": [] } }, "webhooks": { "qrPaymentNotify": { "post": { "tags": [ "QR Payments" ], "summary": "QR payment notify", "description": "Sent by the host to the `notifyUrl` of the payment or refund, unchanged, once it reaches a final status. Optional: MineSec keeps polling `/qr-payments/inquiries` either way. Send it only when the request carried a `notifyUrl`.\n\nSigned with the `notifyKey` MineSec issues at onboarding. The key is hex encoded; decode it to bytes. It is a separate key from the request signing key and, unlike the request signature, the path is not signed:\n\n```\nx-signature: HmacSHA256 {hex( HMAC-SHA256( notifyKey, POST..{x-request-time}..{body} ) )}\n```\n\n- `{body}` is the exact bytes sent.\n- Every retry uses a new `x-request-time` and is signed again. Keep the same `eventId` and body.\n- `amountValue` and `currency` are the order amount of the request, unchanged.\n\n`200` with `{\"respCode\":\"00\"}` means MineSec received the notify. It is also the answer when the notify reports another amount, or a final status other than the one MineSec holds: MineSec reconciles these, and sending them again changes nothing. A notify for a transaction that is already final changes nothing.\n\nRetry when no `200` arrives within 10 seconds, except after a `400` or `404`. Retry 5 s, 10 s, 15 s, 1 min, 5 min, 30 min, 2 h and 6 h after the first attempt, then stop; MineSec's inquiries still settle the transaction. A notify can be delivered more than once.", "parameters": [ { "name": "x-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`HmacSHA256 {hex}`, computed with `notifyKey` over `POST..{x-request-time}..{body}`.", "example": "HmacSHA256 c0bb19e9ab95219a94ca33988c4aad0c13d8c800bcf036a40772f67247267b93" }, { "name": "x-request-time", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ISO 8601 UTC to second precision, the time of this attempt. New on every retry. Rejected when more than 5 minutes off.", "example": "2026-10-13T08:12:07Z" } ], "requestBody": { "description": "Final result of a payment or refund", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonQrNotify" }, "examples": { "Notify, payment": { "value": { "eventId": "evt_8842117", "eventType": "PAYMENT", "eventTime": "2026-10-13T08:12:06.902Z", "respCode": "00", "status": "SUCCESS", "enbrTranId": "tran_01JKF44JBWRNH1AG0GMMKA1M1B", "rrn": "H202610130000123", "networkMerchantId": "2088621900012345", "primaryMid": "111", "primaryTid": "222", "paymentMethod": "ALIPAY", "amountValue": "128.00", "currency": "HKD", "paidAt": "2026-10-13T08:12:05Z", "payer": { "id": "2088102112345678", "fundingSource": "CARD" }, "settlementDate": "2026-10-14", "extra": { "walletTransactionId": "2026101322001412345678901234" } } }, "Notify, refund": { "value": { "eventId": "evt_8842990", "eventType": "REFUND", "eventTime": "2026-10-13T09:40:12.115Z", "respCode": "00", "status": "SUCCESS", "enbrTranId": "tran_01JKF9R1REFUND0000000000001", "linkedEnbrTranId": "tran_01JKF44JBWRNH1AG0GMMKA1M1B", "rrn": "R202610130000031", "orgRrn": "H202610130000123", "paymentMethod": "ALIPAY", "amountValue": "28.00", "currency": "HKD", "refundedAt": "2026-10-13T09:40:11Z", "extra": { "walletTransactionId": "2026101322001412345678909999" } } } } } }, "required": true }, "responses": { "200": { "description": "Received. Also the answer for a notify on a transaction that is already final, with another amount, or with a conflicting final status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StdJsonQrNotifyAck" }, "examples": { "Acknowledged": { "value": { "respCode": "00" } } } } } }, "400": { "description": "The notify does not match the transaction: `enbrTranId` in the body differs from the URL, `eventType` does not match a payment or a refund, the body is not a notify, or the notify profile in the URL is not the one set up for the host. Nothing changed. Do not retry the same content." }, "401": { "description": "Missing or wrong signature, or `x-request-time` more than 5 minutes off. Nothing changed." }, "404": { "description": "Unknown transaction. Nothing changed. Do not retry." } }, "deprecated": false, "security": [] } } }, "components": { "schemas": { "Instant": { "type": "string", "format": "date-time" }, "Currency": { "type": "string" }, "BigDecimal": { "type": "string" }, "StdJsonSignOnResp": { "type": "object", "properties": { "hostReferenceId": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "respCode": { "type": "string" }, "respMessage": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "extra": { "oneOf": [ { "type": "null" }, { "additionalProperties": { "type": "string" }, "type": "object" } ] } }, "required": [ "respCode" ] }, "StdJsonSignOnReq": { "type": "object", "properties": { "acptId": { "type": "string" }, "primaryMid": { "type": "string" }, "primaryTid": { "type": "string" }, "profileId": { "type": "string" }, "subMid": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "subTid": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "timestamp": { "type": "string" }, "trace": { "type": "string" }, "sdkId": { "oneOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "acptId", "primaryMid", "primaryTid", "profileId", "timestamp", "trace" ] }, "StdJsonSignOffResp": { "type": "object", "properties": { "respCode": { "type": "string" }, "respMessage": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "extra": { "oneOf": [ { "type": "null" }, { "additionalProperties": { "type": "string" }, "type": "object" } ] } }, "required": [ "respCode" ] }, "StdJsonSignOffReq": { "type": "object", "properties": { "acptId": { "type": "string" }, "primaryMid": { "type": "string" }, "primaryTid": { "type": "string" }, "profileId": { "type": "string" }, "subMid": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "subTid": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "timestamp": { "type": "string" }, "trace": { "type": "string" } }, "required": [ "acptId", "primaryMid", "primaryTid", "profileId", "timestamp", "trace" ] }, "StdJsonTranResp": { "type": "object", "properties": { "approvalCode": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "hostReferenceId": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "respCode": { "type": "string" }, "respMessage": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "rrn": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "extra": { "oneOf": [ { "type": "null" }, { "additionalProperties": { "type": "string" }, "type": "object" } ] } }, "required": [ "respCode" ] }, "StdJsonTranReq": { "type": "object", "properties": { "acptId": { "type": "string" }, "actionType": { "$ref": "#/components/schemas/ActionType" }, "amountValue": { "type": "string" }, "batchId": { "type": "string" }, "batchNo": { "type": "string" }, "cardData": { "oneOf": [ { "type": "null" }, { "additionalProperties": { "type": "string" }, "type": "object" } ] }, "consumerDevice": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConsumerPaymentDevice" } ] }, "currency": { "type": "string" }, "cvmPerformed": { "$ref": "#/components/schemas/CvmPerformed" }, "enbrTranId": { "type": "string" }, "entryMode": { "$ref": "#/components/schemas/EntryMode" }, "installment": { "description": "Present only on installment sales (`tranType: SALE`) that selected a plan; omitted otherwise, including legacy `tranType: INSTALL` requests, which carry only a count. Carried unchanged on the original request and on its reversal, void/adjust and batch upload, so `externalPlanCode` always matches the original sale even if the plan configuration later changes.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StdJsonInstallment" } ] }, "isReversal": { "type": "boolean" }, "linkedEnbrTranId": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "mcc": { "type": "string" }, "merchantAddress": { "type": "string" }, "merchantDevice": { "$ref": "#/components/schemas/MerchantDevice" }, "merchantName": { "type": "string" }, "orgApprovalCode": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "orgRrn": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "orgTrace": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" }, "pinBlock": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StdJsonPinBlock" } ] }, "posExtra": { "oneOf": [ { "type": "null" }, { "additionalProperties": { "type": "string" }, "type": "object" } ] }, "posReference": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "primaryMid": { "type": "string" }, "primaryTid": { "type": "string" }, "profileId": { "type": "string" }, "sdkId": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "subMid": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "subTid": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "timestamp": { "type": "string" }, "trace": { "type": "string" }, "track2Data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StdJsonTrack2" } ] }, "tranType": { "$ref": "#/components/schemas/TranType" } }, "required": [ "acptId", "actionType", "amountValue", "batchId", "batchNo", "currency", "cvmPerformed", "enbrTranId", "entryMode", "mcc", "merchantAddress", "merchantDevice", "merchantName", "paymentMethod", "primaryMid", "primaryTid", "profileId", "timestamp", "trace", "tranType" ] }, "StdJsonPinBlock": { "type": "object", "description": "Dedicated encrypted PIN block. When present, EMV tag 99 is omitted from cardData.", "properties": { "pinKsn": { "type": "string", "description": "DUKPT KSN for the PIN block key (TDES: 20 hex, AES: 24 hex)." }, "data": { "type": "string", "description": "Hex encrypted PIN block (ISO format-0 for TDES, format-4 for AES)." } }, "required": [ "pinKsn", "data" ] }, "StdJsonTrack2": { "type": "object", "description": "Dedicated encrypted Track2 data. When present, EMV tag 57 is omitted from cardData; read the PAN from here after decryption.", "properties": { "track2Ksn": { "type": "string", "description": "DUKPT KSN for the Track2 data key." }, "data": { "type": "string", "description": "Hex encrypted Track2 data (DUKPT data-encryption)." }, "track2Length": { "type": "integer", "description": "Number of hex characters of Track2 before encryption. The plaintext is zero-padded up to the cipher block size (8 bytes TDES, 16 bytes AES) before encryption, so after decrypting take the first track2Length hex characters and discard the rest. Counts hex characters, not bytes: 38 means 19 bytes of Track2.", "example": 38 } }, "required": [ "track2Ksn", "data", "track2Length" ] }, "StdJsonInstallment": { "type": "object", "description": "Resolved installment instruction. MineSec validates the selection against the merchant's configured plans before sending; the host must not calculate interest or amortization from it.", "properties": { "installmentCount": { "type": "integer", "minimum": 1, "description": "Number of installments. For REVOLVING it applies to `revolving.remainingAmount`, excluding the initial payment.", "example": 6 }, "interestModel": { "$ref": "#/components/schemas/InterestModel" }, "installmentType": { "$ref": "#/components/schemas/InstallmentType" }, "externalPlanCode": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Acquirer-defined plan code, when the integration requires one.", "example": "BNK06" }, "revolving": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Revolving" } ], "description": "Present only when `installmentType` is REVOLVING." }, "issuerPreapprovalReference": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Issuer preapproval reference, when required and available." } }, "required": [ "installmentCount", "interestModel", "installmentType" ] }, "Revolving": { "type": "object", "description": "Split of the transaction amount for a REVOLVING installment: 0 < initialPaymentAmount < amountValue, and remainingAmount = amountValue - initialPaymentAmount.", "properties": { "initialPaymentAmount": { "$ref": "#/components/schemas/Amount", "description": "Amount paid upfront. Same currency as the transaction; value uses the currency's ISO decimal fraction, as `amountValue`." }, "remainingAmount": { "$ref": "#/components/schemas/Amount", "description": "Amount spread over `installmentCount`. Same currency as the transaction; value uses the currency's ISO decimal fraction, as `amountValue`." } }, "required": [ "initialPaymentAmount", "remainingAmount" ] }, "InterestModel": { "type": "string", "enum": [ "WITH_INTEREST", "NO_INTEREST" ] }, "InstallmentType": { "type": "string", "enum": [ "REGULAR", "REVOLVING" ] }, "ActionType": { "type": "string", "enum": [ "NEW", "ADJUST", "VOID", "AUTH_COMP", "LINK_REFUND", "CONFIRM", "MERCHANT_PRESENT_QR", "CONSUMER_PRESENT_QR", "NOTIFIED", "INQUIRY", "CLOSE", "INCREMENTAL_AUTH" ] }, "ConsumerPaymentDevice": { "type": "string", "enum": [ "Card", "MobilePhone", "Tablet", "MiniCard", "Watch", "MobileTag", "KeyFob", "Case", "Other" ] }, "CvmPerformed": { "type": "string", "enum": [ "NO_CVM", "SIGNATURE", "PIN", "OFFLINE_PIN", "CDCVM" ] }, "EntryMode": { "type": "string", "enum": [ "NFC", "SWIPE", "CHIP", "FALLBACK", "MANUAL_KEYED", "MERCHANT_PRESENT", "CONSUMER_PRESENT", "RETRIEVE", "UNKNOWN" ] }, "MerchantDevice": { "type": "string", "enum": [ "SOFTPOS", "TERMINAL", "MPOS", "OTHER" ] }, "PaymentMethod": { "type": "string", "enum": [ "VISA", "MASTERCARD", "UNIONPAY", "AMEX", "JCB", "DISCOVER", "DINERS", "MAESTRO", "HIMYAN", "NAPS", "MY_DEBIT", "ELO", "CPACE", "NAPAS", "TROY", "TAKAPAY", "SADEEQ", "UNKNOWN" ] }, "TranType": { "type": "string", "enum": [ "SALE", "REFUND", "AUTH", "AUTH_COMP", "DEFERRED_AUTH", "INSTALL" ] }, "StdJsonSettleResp": { "type": "object", "properties": { "hostReferenceId": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "respCode": { "type": "string" }, "respMessage": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "extra": { "oneOf": [ { "type": "null" }, { "additionalProperties": { "type": "string" }, "type": "object" } ] } }, "required": [ "respCode" ] }, "StdJsonSettleReq": { "type": "object", "properties": { "acptId": { "type": "string" }, "batchId": { "type": "string" }, "batchNo": { "type": "string" }, "isSecond": { "type": "boolean" }, "primaryMid": { "type": "string" }, "primaryTid": { "type": "string" }, "profileId": { "type": "string" }, "subMid": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "subTid": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "summary": { "items": { "$ref": "#/components/schemas/TranTypeSummary" }, "type": "array" }, "timestamp": { "type": "string" }, "trace": { "type": "string" } }, "required": [ "acptId", "batchId", "batchNo", "primaryMid", "primaryTid", "profileId", "summary", "timestamp", "trace" ] }, "TranTypeSummary": { "type": "object", "properties": { "count": { "type": "number", "format": "int32" }, "paymentMethod": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentMethod" } ] }, "total": { "$ref": "#/components/schemas/Amount" }, "tranStatus": { "$ref": "#/components/schemas/TranStatus" }, "tranType": { "$ref": "#/components/schemas/TranType" } }, "required": [ "count", "total", "tranStatus", "tranType" ] }, "Amount": { "type": "object", "properties": { "currency": { "type": "string" }, "value": { "type": "string" } }, "required": [ "currency", "value" ] }, "TranStatus": { "type": "string", "enum": [ "PROCESSING", "APPROVED", "DECLINED", "VOIDED", "REVERSED", "AUTH_ONLY", "ADJUSTED" ] }, "QrPaymentMethod": { "type": "string", "description": "Payment methods accepted on the QR endpoints. `UNIFIED_QR` is the aggregated code: the host identifies the wallet and returns the concrete method on `SUCCESS`.", "enum": [ "ALIPAY", "WECHAT", "VISA_QR", "MASTERCARD_QR", "UNIONPAY_QR", "SHOPEE_PAY_QR", "GRAB_PAY_QR", "ALIPAY_PLUS_QR", "DUIT_NOW_QR", "PAY_NOW", "PH_QR", "JCB_EMV_QR", "LINEPAY_QR", "EZ_PAY", "PI_QR", "ESUNWALLET_QR", "TAIWANPAY_QR", "EASYWALLET_QR", "JKOPAY_QR", "IPASSMONEY_PAY_QR", "ICASH_PAY_QR", "PLUSPAY_QR", "PXPAYPLUS_QR", "GAMA_PAY_QR", "OPAY_QR", "LINEPAYMONEY_QR", "PAYPAY_QR", "BCCARD_QR", "NETS_QR", "NTTDATA_QR", "UCARD", "CUP", "SMARTPAY", "BONUSPAY_QR", "CASHLEZ_QR", "UNIFIED_QR" ] }, "QrMode": { "type": "string", "description": "`MPQR`: merchant presented, the host returns a QR to display. `CPQR`: consumer presented, the merchant scans the customer's code and the host charges it.", "enum": [ "MPQR", "CPQR" ] }, "QrStatus": { "type": "string", "description": "The only field MineSec uses for the outcome. `CLOSED`: cancelled or expired before any money moved. `REVERSED`: charged, then returned by a cancellation.", "enum": [ "PENDING", "SUCCESS", "FAILED", "CLOSED", "REVERSED" ] }, "QrFailureCode": { "type": "string", "description": "Why a payment or refund is `FAILED`. Use one of the listed codes where one fits: `CODE_EXPIRED`, `CODE_INVALID`, `INSUFFICIENT_FUNDS`, `USER_CANCELLED`, `RISK_REJECTED`, `LIMIT_EXCEEDED`, `UNSUPPORTED_WALLET`, `DUPLICATE`, `SYSTEM_ERROR`. `UNSUPPORTED_WALLET`: the host cannot place a `UNIFIED_QR` consumer code, or the merchant does not accept its wallet. A code outside the list is accepted and treated as a generic failure.", "examples": [ "CODE_EXPIRED", "CODE_INVALID", "INSUFFICIENT_FUNDS", "USER_CANCELLED", "RISK_REJECTED", "LIMIT_EXCEEDED", "UNSUPPORTED_WALLET", "DUPLICATE", "SYSTEM_ERROR" ] }, "QrConsumerCodeFormat": { "type": "string", "description": "How the scanned consumer code is encoded.", "enum": [ "BARCODE_NUMERIC", "QR_TEXT", "EMV_CPM_BASE64" ] }, "QrScanMethod": { "type": "string", "description": "How the merchant captured the consumer code.", "enum": [ "CAMERA", "SCANNER" ] }, "QrCodeFormat": { "type": "string", "description": "How `qrCode.content` is to be rendered.", "enum": [ "EMVCO_MPM", "URL", "RAW" ] }, "QrInquiryType": { "type": "string", "description": "Whether `enbrTranId` names a payment or a refund.", "enum": [ "PAYMENT", "REFUND" ] }, "QrCancelReason": { "type": "string", "description": "`TIMEOUT`: MineSec got no final status in time. `MERCHANT_VOID`: the merchant voids a paid transaction.", "enum": [ "USER_CANCELLED", "TIMEOUT", "MERCHANT_VOID" ] }, "QrEventType": { "type": "string", "description": "Whether the notify reports a payment or a refund.", "enum": [ "PAYMENT", "REFUND" ] }, "StdJsonQrConsumerCode": { "type": "object", "description": "The customer's code scanned by the merchant.", "properties": { "value": { "type": "string", "description": "The scanned content. A one-time payment token." }, "format": { "$ref": "#/components/schemas/QrConsumerCodeFormat" }, "scanMethod": { "$ref": "#/components/schemas/QrScanMethod" } }, "required": [ "value", "format" ] }, "StdJsonQrCode": { "type": "object", "description": "The QR to display.", "properties": { "content": { "type": "string", "description": "The payload to render as a QR." }, "format": { "$ref": "#/components/schemas/QrCodeFormat" }, "reference": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Reference carried inside the QR, e.g. the EMVCo reference label seen on the payer's statement." } }, "required": [ "content", "format" ] }, "StdJsonQrPayer": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "The wallet's opaque user id." }, "institution": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "The payer's bank or wallet, for national schemes." }, "maskedAccount": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "fundingSource": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "e.g. `BALANCE`, `CARD`." } }, "required": [] }, "StdJsonQrPaymentReq": { "type": "object", "description": "Creates an MPQR order or charges a scanned CPQR code. `consumerCode` is required for `CPQR`.", "properties": { "enbrTranId": { "type": "string", "description": "Idempotency key of the payment." }, "srsTranId": { "type": "string", "description": "The transaction id shown on the SRS side and the portal." }, "trace": { "type": "string", "description": "Per-message sequence number." }, "posReference": { "type": "string" }, "extOrderId": { "type": "string", "description": "The merchant's own order number." }, "pboId": { "type": "string", "description": "MineSec tenant." }, "isvId": { "type": "string" }, "profileId": { "type": "string", "description": "MineSec merchant profile." }, "providerMchId": { "type": "string", "description": "The merchant id in the provider's own system." }, "providerReference": { "type": "string", "description": "The merchant reference in the provider's own system." }, "shopId": { "type": "string" }, "shopName": { "type": "string" }, "acptId": { "type": "string", "description": "The acceptance (routing entry) used." }, "primaryMid": { "type": "string" }, "primaryTid": { "type": "string" }, "subMid": { "type": "string", "description": "Wallet sub-merchant id." }, "subTid": { "type": "string" }, "sdkId": { "type": "string", "description": "The SoftPOS device." }, "operatorId": { "type": "string", "description": "Cashier." }, "merchantDevice": { "$ref": "#/components/schemas/MerchantDevice" }, "qrMode": { "$ref": "#/components/schemas/QrMode" }, "tranType": { "type": "string", "enum": [ "SALE" ], "description": "Only `SALE` is supported." }, "amountValue": { "type": "string", "description": "Same formatting as `/transactions`." }, "currency": { "type": "string" }, "paymentMethod": { "$ref": "#/components/schemas/QrPaymentMethod" }, "acceptedPaymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/QrPaymentMethod" }, "minItems": 1, "description": "Optional, `MPQR` with `UNIFIED_QR` only: the wallets the host may put in the code. When absent, the host uses the wallets it has enabled for the merchant. Not sent for `CPQR`: the host identifies the wallet from `consumerCode`." }, "tipAmount": { "type": "string", "description": "Already included in `amountValue`." }, "consumerCode": { "$ref": "#/components/schemas/StdJsonQrConsumerCode" }, "qrExpirySeconds": { "type": "integer", "minimum": 1, "description": "MPQR: requested validity. The host may shorten it; `expiresAt` in the response is authoritative." }, "notifyUrl": { "type": "string", "description": "Where to send the notify for this transaction. Call it unchanged, never build it. Omitted when no notify is set up for the host." }, "merchantName": { "type": "string" }, "merchantAddress": { "type": "string" }, "merchantCity": { "type": "string", "description": "EMVCo MPM tag 60." }, "merchantCountry": { "type": "string", "description": "ISO 3166-1 alpha-2. EMVCo MPM tag 58." }, "merchantPostalCode": { "type": "string" }, "mcc": { "type": "string" }, "terminalIp": { "type": "string", "description": "Mandatory for some wallets." }, "batchId": { "type": "string", "description": "For reference only. QR is normally host-captured." }, "batchNo": { "type": "string", "description": "For reference only." }, "posExtra": { "type": "object", "additionalProperties": { "type": "string" } }, "timestamp": { "type": "string" } }, "required": [ "acptId", "amountValue", "currency", "enbrTranId", "mcc", "merchantAddress", "merchantCity", "merchantCountry", "merchantDevice", "merchantName", "paymentMethod", "pboId", "primaryMid", "primaryTid", "profileId", "qrMode", "timestamp", "trace", "tranType" ], "allOf": [ { "if": { "properties": { "qrMode": { "const": "CPQR" } }, "required": [ "qrMode" ] }, "then": { "required": [ "consumerCode" ] } } ] }, "StdJsonQrInquiryReq": { "type": "object", "properties": { "enbrTranId": { "type": "string", "description": "The payment or the refund being queried." }, "srsTranId": { "type": "string", "description": "The transaction id shown on the SRS side and the portal." }, "trace": { "type": "string", "description": "Per-message sequence number." }, "posReference": { "type": "string" }, "extOrderId": { "type": "string", "description": "The merchant's own order number." }, "pboId": { "type": "string", "description": "MineSec tenant." }, "isvId": { "type": "string" }, "profileId": { "type": "string", "description": "MineSec merchant profile." }, "providerMchId": { "type": "string", "description": "The merchant id in the provider's own system." }, "providerReference": { "type": "string", "description": "The merchant reference in the provider's own system." }, "shopId": { "type": "string" }, "shopName": { "type": "string" }, "acptId": { "type": "string", "description": "The acceptance (routing entry) used." }, "primaryMid": { "type": "string" }, "primaryTid": { "type": "string" }, "subMid": { "type": "string", "description": "Wallet sub-merchant id." }, "subTid": { "type": "string" }, "sdkId": { "type": "string", "description": "The SoftPOS device." }, "operatorId": { "type": "string", "description": "Cashier." }, "inquiryType": { "$ref": "#/components/schemas/QrInquiryType" }, "rrn": { "type": "string", "description": "`rrn` from the host's create response. Sent when known.", "maxLength": 64 }, "batchId": { "type": "string", "description": "For reference only. QR is normally host-captured." }, "batchNo": { "type": "string", "description": "For reference only." }, "timestamp": { "type": "string" } }, "required": [ "acptId", "enbrTranId", "inquiryType", "pboId", "primaryMid", "primaryTid", "profileId", "timestamp", "trace" ] }, "StdJsonQrCancellationReq": { "type": "object", "properties": { "enbrTranId": { "type": "string", "description": "The payment being cancelled." }, "enbrActionId": { "type": "string", "description": "Tells two cancellation attempts on one payment apart." }, "srsTranId": { "type": "string", "description": "The transaction id shown on the SRS side and the portal." }, "trace": { "type": "string", "description": "Per-message sequence number." }, "posReference": { "type": "string" }, "extOrderId": { "type": "string", "description": "The merchant's own order number." }, "pboId": { "type": "string", "description": "MineSec tenant." }, "isvId": { "type": "string" }, "profileId": { "type": "string", "description": "MineSec merchant profile." }, "providerMchId": { "type": "string", "description": "The merchant id in the provider's own system." }, "providerReference": { "type": "string", "description": "The merchant reference in the provider's own system." }, "shopId": { "type": "string" }, "shopName": { "type": "string" }, "acptId": { "type": "string", "description": "The acceptance (routing entry) used." }, "primaryMid": { "type": "string" }, "primaryTid": { "type": "string" }, "subMid": { "type": "string", "description": "Wallet sub-merchant id." }, "subTid": { "type": "string" }, "sdkId": { "type": "string", "description": "The SoftPOS device." }, "operatorId": { "type": "string", "description": "Cashier." }, "reason": { "$ref": "#/components/schemas/QrCancelReason" }, "rrn": { "type": "string", "description": "`rrn` from the host's create response. Sent when known.", "maxLength": 64 }, "batchId": { "type": "string", "description": "For reference only. QR is normally host-captured." }, "batchNo": { "type": "string", "description": "For reference only." }, "timestamp": { "type": "string" } }, "required": [ "acptId", "enbrActionId", "enbrTranId", "pboId", "primaryMid", "primaryTid", "profileId", "reason", "timestamp", "trace" ] }, "StdJsonQrRefundReq": { "type": "object", "properties": { "enbrTranId": { "type": "string", "description": "Idempotency key of the refund itself, not the original payment." }, "srsTranId": { "type": "string", "description": "The transaction id shown on the SRS side and the portal." }, "trace": { "type": "string", "description": "Per-message sequence number." }, "posReference": { "type": "string" }, "extOrderId": { "type": "string", "description": "The merchant's own order number." }, "pboId": { "type": "string", "description": "MineSec tenant." }, "isvId": { "type": "string" }, "profileId": { "type": "string", "description": "MineSec merchant profile." }, "providerMchId": { "type": "string", "description": "The merchant id in the provider's own system." }, "providerReference": { "type": "string", "description": "The merchant reference in the provider's own system." }, "shopId": { "type": "string" }, "shopName": { "type": "string" }, "acptId": { "type": "string", "description": "The acceptance (routing entry) used." }, "primaryMid": { "type": "string" }, "primaryTid": { "type": "string" }, "subMid": { "type": "string", "description": "Wallet sub-merchant id." }, "subTid": { "type": "string" }, "sdkId": { "type": "string", "description": "The SoftPOS device." }, "operatorId": { "type": "string", "description": "Cashier." }, "amountValue": { "type": "string", "description": "Amount to refund. Same formatting as `/transactions`." }, "currency": { "type": "string" }, "reason": { "type": "string", "description": "Free text." }, "notifyUrl": { "type": "string", "description": "Where to send the notify for this transaction. Call it unchanged, never build it. Omitted when no notify is set up for the host." }, "linkedEnbrTranId": { "type": "string", "description": "The original payment." }, "orgRrn": { "type": "string", "description": "`rrn` of the original payment.", "maxLength": 64 }, "batchId": { "type": "string", "description": "For reference only. QR is normally host-captured." }, "batchNo": { "type": "string", "description": "For reference only." }, "timestamp": { "type": "string" } }, "required": [ "acptId", "amountValue", "currency", "enbrTranId", "linkedEnbrTranId", "orgRrn", "pboId", "primaryMid", "primaryTid", "profileId", "timestamp", "trace" ] }, "StdJsonQrResult": { "type": "object", "description": "Result of a QR payment or refund. Returned by every `/qr-payments` endpoint and sent as the notify body.", "properties": { "respCode": { "type": "string", "description": "The host's own result code, kept for diagnostics. Must be `00` when `status` is `PENDING` or `SUCCESS`." }, "respMessage": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Human-readable result. Required when `status` is `FAILED`." }, "status": { "$ref": "#/components/schemas/QrStatus" }, "failureCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/QrFailureCode" } ], "description": "Required when `status` is `FAILED`." }, "enbrTranId": { "type": "string", "description": "Echo of the request." }, "rrn": { "oneOf": [ { "type": "null" }, { "type": "string", "maxLength": 64 } ], "description": "The host's own reference for this payment or refund, issued at create time. MineSec stores it, sends it back on every follow-up call and searches by it. Required when `status` is `PENDING`, `SUCCESS` or `REVERSED`, and the same value in every response for one payment. It may be absent only when the host holds no order: a payment rejected before an order was created, or a cancellation for a create the host never received. Put the wallet's own transaction id, if different, in `extra.walletTransactionId`." }, "approvalCode": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Card scheme QR only." }, "networkMerchantId": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "The merchant id on the wallet or scheme side." }, "primaryMid": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Echo of the request. Expected on a notify." }, "primaryTid": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Echo of the request. Expected on a notify." }, "paymentMethod": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Required when `status` is `SUCCESS`, and then concrete, never `UNIFIED_QR`. A `QrPaymentMethod` value. A wallet missing from that list is still accepted; ask MineSec to add it." }, "amountValue": { "type": "string", "description": "Echo of the request. Checked by MineSec." }, "currency": { "type": "string", "description": "Echo of the request. Checked by MineSec." }, "qrCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StdJsonQrCode" } ], "description": "MPQR: the QR to display while `status` is `PENDING`." }, "expiresAt": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "MPQR: when the QR stops being payable. ISO 8601 UTC." }, "paidAt": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the payment succeeded. ISO 8601 UTC." }, "payer": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StdJsonQrPayer" } ] }, "payerAmount": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Cross-border wallets: what the payer was charged." }, "exchangeRate": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "discountAmount": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "settlementDate": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "settlementReference": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "linkedEnbrTranId": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Refunds: the original payment." }, "orgRrn": { "oneOf": [ { "type": "null" }, { "type": "string", "maxLength": 64 } ], "description": "Refunds: `rrn` of the original payment." }, "refundedAt": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Refunds: when the refund succeeded. ISO 8601 UTC." }, "refundedAmount": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Refund inquiries: the amount refunded." }, "extra": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": { "type": "string" } } ], "description": "Host-specific values, stored with the transaction. `walletTransactionId`: the wallet or scheme transaction id (the number on the payer's receipt), when it differs from `rrn`." } }, "required": [ "amountValue", "currency", "enbrTranId", "respCode", "status" ], "allOf": [ { "if": { "properties": { "status": { "enum": [ "PENDING", "SUCCESS" ] } }, "required": [ "status" ] }, "then": { "properties": { "respCode": { "const": "00" } } } }, { "if": { "properties": { "status": { "enum": [ "SUCCESS" ] } }, "required": [ "status" ] }, "then": { "required": [ "paymentMethod" ], "properties": { "paymentMethod": { "type": "string", "not": { "const": "UNIFIED_QR" } } } } }, { "if": { "properties": { "status": { "enum": [ "FAILED" ] } }, "required": [ "status" ] }, "then": { "required": [ "failureCode", "respMessage" ], "properties": { "failureCode": { "type": "string" }, "respMessage": { "type": "string" } } } }, { "if": { "properties": { "status": { "enum": [ "PENDING", "SUCCESS", "REVERSED" ] } }, "required": [ "status" ] }, "then": { "required": [ "rrn" ], "properties": { "rrn": { "type": "string" } } } } ] }, "StdJsonQrNotify": { "type": "object", "description": "The fields of `StdJsonQrResult` plus the event. Sent once per final status, never for `PENDING`.", "properties": { "eventId": { "type": "string", "description": "Unique per event. Repeated on a retry of the same event." }, "eventType": { "$ref": "#/components/schemas/QrEventType" }, "eventTime": { "type": "string", "description": "ISO 8601 UTC." }, "respCode": { "type": "string", "description": "The host's own result code, kept for diagnostics. Must be `00` when `status` is `PENDING` or `SUCCESS`." }, "respMessage": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Human-readable result. Required when `status` is `FAILED`." }, "status": { "$ref": "#/components/schemas/QrStatus" }, "failureCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/QrFailureCode" } ], "description": "Required when `status` is `FAILED`." }, "enbrTranId": { "type": "string", "description": "Echo of the request." }, "rrn": { "oneOf": [ { "type": "null" }, { "type": "string", "maxLength": 64 } ], "description": "The host's own reference for this payment or refund, issued at create time. MineSec stores it, sends it back on every follow-up call and searches by it. Required when `status` is `PENDING`, `SUCCESS` or `REVERSED`, and the same value in every response for one payment. It may be absent only when the host holds no order: a payment rejected before an order was created, or a cancellation for a create the host never received. Put the wallet's own transaction id, if different, in `extra.walletTransactionId`." }, "approvalCode": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Card scheme QR only." }, "networkMerchantId": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "The merchant id on the wallet or scheme side." }, "primaryMid": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Echo of the request. Expected on a notify." }, "primaryTid": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Echo of the request. Expected on a notify." }, "paymentMethod": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Required when `status` is `SUCCESS`, and then concrete, never `UNIFIED_QR`. A `QrPaymentMethod` value. A wallet missing from that list is still accepted; ask MineSec to add it." }, "amountValue": { "type": "string", "description": "Echo of the request. Checked by MineSec." }, "currency": { "type": "string", "description": "Echo of the request. Checked by MineSec." }, "qrCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StdJsonQrCode" } ], "description": "MPQR: the QR to display while `status` is `PENDING`." }, "expiresAt": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "MPQR: when the QR stops being payable. ISO 8601 UTC." }, "paidAt": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the payment succeeded. ISO 8601 UTC." }, "payer": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StdJsonQrPayer" } ] }, "payerAmount": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Cross-border wallets: what the payer was charged." }, "exchangeRate": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "discountAmount": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "settlementDate": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "settlementReference": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "linkedEnbrTranId": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Refunds: the original payment." }, "orgRrn": { "oneOf": [ { "type": "null" }, { "type": "string", "maxLength": 64 } ], "description": "Refunds: `rrn` of the original payment." }, "refundedAt": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Refunds: when the refund succeeded. ISO 8601 UTC." }, "refundedAmount": { "oneOf": [ { "type": "null" }, { "type": "string" } ], "description": "Refund inquiries: the amount refunded." }, "extra": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": { "type": "string" } } ], "description": "Host-specific values, stored with the transaction. `walletTransactionId`: the wallet or scheme transaction id (the number on the payer's receipt), when it differs from `rrn`." } }, "required": [ "amountValue", "currency", "enbrTranId", "eventId", "eventTime", "eventType", "respCode", "status" ], "allOf": [ { "if": { "properties": { "status": { "enum": [ "PENDING", "SUCCESS" ] } }, "required": [ "status" ] }, "then": { "properties": { "respCode": { "const": "00" } } } }, { "if": { "properties": { "status": { "enum": [ "SUCCESS" ] } }, "required": [ "status" ] }, "then": { "required": [ "paymentMethod" ], "properties": { "paymentMethod": { "type": "string", "not": { "const": "UNIFIED_QR" } } } } }, { "if": { "properties": { "status": { "enum": [ "FAILED" ] } }, "required": [ "status" ] }, "then": { "required": [ "failureCode", "respMessage" ], "properties": { "failureCode": { "type": "string" }, "respMessage": { "type": "string" } } } }, { "if": { "properties": { "status": { "enum": [ "PENDING", "SUCCESS", "REVERSED" ] } }, "required": [ "status" ] }, "then": { "required": [ "rrn" ], "properties": { "rrn": { "type": "string" } } } }, { "properties": { "status": { "enum": [ "SUCCESS", "FAILED", "CLOSED", "REVERSED" ] } } } ] }, "StdJsonQrNotifyAck": { "type": "object", "properties": { "respCode": { "type": "string" }, "respMessage": { "oneOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "respCode" ] } }, "securitySchemes": { "BearerAuth": { "bearerFormat": "jwt", "type": "http", "scheme": "bearer" } } }, "security": [ { "BearerAuth": [] } ], "tags": [] }