Publish API

Push a transaction request to a physical POS device via Valor Connect. The device will prompt the cardholder to present their card and complete the payment.

Response — 200 OK (Approved)

Returned when the transaction is completed and approved by the device.

{
  "error_no": "S00",
  "response": {
    "STATE": "0",
    "EPI": "2226572534",
    "SERIAL_NO": "125214406457",
    "MER_TXN_ID": "INV001",
    "TRAN_TYPE": "Credit",
    "CARD_PROCESSED_AS": "Credit",
    "CARD_TYPE": "Credit",
    "TRAN_METHOD": "Sale",
    "TXN_ID": "223128674107",
    "TXN_DETAILS_UPLOADED": "YES",
    "AMOUNT": "100",
    "STATE_TAX": "3",
    "TAXES": {
      "STATE_TAX": {
        "RATE": "3.000",
        "AMOUNT": "3",
        "TAXABLE_AMOUNT": "100"
      },
      "TAX_PROFILE": "TMS Tax",
      "TOTAL_TAXES": "3",
      "TOTAL_WITH_TAX": "103"
    },
    "PARTIAL": "0",
    "MASKED_PAN": "4111 **** **** 1111",
    "ENTRY_MODE": "MANUAL",
    "ENTRY_TYPE": " ",
    "EXPIRY_DATE": "3012",
    "RRN": "611906500120",
    "CODE": "TAS410",
    "AUTH_RSP_TEXT": "APPROVAL TAS410",
    "DATE": "29042026 02:08:48",
    "TRAN_NO": "1",
    "BATCH_NO": "231",
    "ISSUER": "VISA",
    "TOTAL_AMOUNT": "103",
    "STAN_ID": "18",
    "CUSTOMER_NAME": "NJU",
    "MID": "887000003198",
    "TID": "75021674"
  }
}

Response — 200 OK (Cancelled / Timed Out)

Returned when the transaction was sent to the device but was cancelled by the cardholder or timed out before completion.

{
  "error_no": "S00",
  "response": {
    "STATE": "-1",
    "EPI": "2226572534",
    "SERIAL_NO": "125214406457",
    "ERROR_MSG": "Transaction Timeout/Cancelled",
    "MER_TXN_ID": "INV001"
  }
}

Response fields — top level

Field	Type	Description
`error_no`	string	`S00` indicates the request was processed. Check `response.STATE` to determine the transaction outcome
`response`	object	Transaction result object (see below)

`response` — approved transaction fields

Field	Type	Description
`STATE`	string	Transaction state. `0` = approved; `-1` = cancelled or timed out
`EPI`	string	Terminal EPI identifier
`SERIAL_NO`	string	Device serial number
`MER_TXN_ID`	string	Merchant-supplied transaction reference (invoice number)
`TRAN_TYPE`	string	Card transaction type (e.g. `Credit`, `Debit`)
`CARD_PROCESSED_AS`	string	How the card was processed (e.g. `Credit`, `Debit`)
`CARD_TYPE`	string	Card type (e.g. `Credit`, `Debit`)
`TRAN_METHOD`	string	Transaction method (e.g. `Sale`, `Refund`)
`TXN_ID`	string	Unique transaction identifier assigned by the processor
`TXN_DETAILS_UPLOADED`	string	`YES` if transaction details have been uploaded to the server
`AMOUNT`	string	Base transaction amount in cents
`STATE_TAX`	string	State tax amount in cents
`TAXES`	object	Tax breakdown details (see below)
`PARTIAL`	string	`1` if partially approved; `0` for full approval
`MASKED_PAN`	string	Masked card number (e.g. `4111 ** ** 1111`)
`ENTRY_MODE`	string	Card entry method (e.g. `MANUAL`, `SWIPE`, `CHIP`, `CONTACTLESS`)
`ENTRY_TYPE`	string	Entry type indicator
`EXPIRY_DATE`	string	Card expiry in `MMYY` format (e.g. `3012` = December 2030)
`RRN`	string	Retrieval reference number for reconciliation
`CODE`	string	Issuer-returned authorization code
`AUTH_RSP_TEXT`	string	Full authorization response text from the issuer
`DATE`	string	Transaction timestamp in `DDMMYYYY HH:MM:SS` format
`TRAN_NO`	string	Sequential transaction number within the batch
`BATCH_NO`	string	Settlement batch number
`ISSUER`	string	Card network (e.g. `VISA`, `MASTERCARD`)
`TOTAL_AMOUNT`	string	Total charged amount including taxes in cents
`STAN_ID`	string	System trace audit number
`CUSTOMER_NAME`	string	Cardholder name, if captured
`MID`	string	Merchant ID
`TID`	string	Terminal ID

`TAXES` object

Field	Type	Description
`STATE_TAX.RATE`	string	State tax rate as a percentage
`STATE_TAX.AMOUNT`	string	State tax amount in cents
`STATE_TAX.TAXABLE_AMOUNT`	string	Amount subject to state tax in cents
`TAX_PROFILE`	string	Name of the tax profile applied
`TOTAL_TAXES`	string	Total tax amount in cents
`TOTAL_WITH_TAX`	string	Total charged amount including all taxes in cents

`response` — cancelled / timed out fields

Field	Type	Description
`STATE`	string	`-1` indicates the transaction was cancelled or timed out
`EPI`	string	Terminal EPI identifier
`SERIAL_NO`	string	Device serial number
`ERROR_MSG`	string	Description of the cancellation reason (e.g. `Transaction Timeout/Cancelled`)
`MER_TXN_ID`	string	Merchant-supplied transaction reference

Note: Both approved and cancelled outcomes return error_no: "S00" with HTTP 200. Always check response.STATE to determine the actual outcome — "0" = approved, "-1" = cancelled or timed out.

Response — 400 (Processing Error)

{
  "error_no": "VC03",
  "mesg": "PROCESSING ERROR",
  "msg": "PROCESSING ERROR",
  "desc": "DEVICE OFFLINE"
}

Response fields

Field	Type	Description
`error_no`	string	`VC03` indicates the device is offline and cannot receive the request
`mesg`	string	Error message
`msg`	string	Error message
`desc`	string	Detailed description of the error cause

Error code reference

`error_no`	`STATE`	Meaning	Typical cause
`S00`	`0`	Approved	Transaction completed and approved on the device
`S00`	`-1`	Cancelled / timed out	Cardholder cancelled or did not present card within the timeout period
`VC03`	—	Processing error	Device is offline and not reachable via Valor Connect

Status API

Poll the status of a transaction previously published to a POS device via Valor Connect. Use this endpoint to retrieve the result after calling the Publish API.

Response — 200 OK (Approved)

{
  "error_no": "S00",
  "response": {
    "STATE": "0",
    "EPI": "2226572534",
    "SERIAL_NO": "125214406457",
    "MER_TXN_ID": "INV001",
    "TRAN_TYPE": "Credit",
    "CARD_PROCESSED_AS": "Credit",
    "CARD_TYPE": "Credit",
    "TRAN_METHOD": "Sale",
    "TXN_ID": "223128674107",
    "TXN_DETAILS_UPLOADED": "YES",
    "AMOUNT": "100",
    "STATE_TAX": "3",
    "TAXES": {
      "STATE_TAX": {
        "RATE": "3.000",
        "AMOUNT": "3",
        "TAXABLE_AMOUNT": "100"
      },
      "TAX_PROFILE": "TMS Tax",
      "TOTAL_TAXES": "3",
      "TOTAL_WITH_TAX": "103"
    },
    "PARTIAL": "0",
    "MASKED_PAN": "4111 **** **** 1111",
    "ENTRY_MODE": "MANUAL",
    "ENTRY_TYPE": " ",
    "EXPIRY_DATE": "3012",
    "RRN": "611906500120",
    "CODE": "TAS410",
    "AUTH_RSP_TEXT": "APPROVAL TAS410",
    "DATE": "29042026 02:08:48",
    "TRAN_NO": "1",
    "BATCH_NO": "231",
    "ISSUER": "VISA",
    "TOTAL_AMOUNT": "103",
    "STAN_ID": "18",
    "CUSTOMER_NAME": "NJU",
    "MID": "887000003198",
    "TID": "75021674"
  }
}

Note: The response object schema is identical to the Publish API approved response. Refer to the Publish API field reference for full field descriptions.

Response — 400 (Processing Error)

{
  "error_no": "VC09",
  "mesg": "PROCESSING ERROR",
  "msg": "PROCESSING ERROR",
  "desc": "UNABLE TO FETCH TRANSACTION STATUS"
}

Response fields

Field	Type	Description
`error_no`	string	`VC09` indicates the transaction status could not be retrieved
`mesg`	string	Error message
`msg`	string	Error message
`desc`	string	Detailed description of the error cause

Error code reference

`error_no`	Meaning	Typical cause
`S00`	Success	Transaction status retrieved
`VC09`	Processing error	Transaction status is unavailable — the device may not have responded or the `MER_TXN_ID` is invalid

Cancel API

Send a cancellation request to a POS device to abort a transaction that is currently in progress via Valor Connect.

Response — 200 OK

{
  "error_no": "S00",
  "response": "Cancel Request has been send to POS."
}

Response fields

Field	Type	Description
`error_no`	string	`S00` indicates the cancel request was sent successfully
`response`	string	Confirmation message that the cancel request was dispatched to the device

Note: A successful response indicates the cancellation request was transmitted to the device, not that the transaction was necessarily cancelled. Use the Status API to confirm the final transaction state.

Response — 400 (Processing Error)

{
  "error_no": "D07",
  "mesg": "PROCESSING ERROR",
  "msg": "PROCESSING ERROR",
  "desc": "NOT A VALID APP KEY"
}

Response fields

Field	Type	Description
`error_no`	string	`D07` indicates an invalid App Key
`mesg`	string	Error message
`msg`	string	Error message
`desc`	string	Detailed description of the error cause

Error code reference

`error_no`	Meaning	Typical cause
`S00`	Success	Cancel request sent to the device
`D07`	Processing error	App Key is invalid or unrecognised

Valor Connect Device Status

Retrieve the online/offline status of all Valor Connect-enabled terminals associated with a merchant.

Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "devices": [
    {
      "EPI": "2319914293",
      "topic": "c127d*******d317c7b/UAT/VC/2319914293/POS",
      "Label": "Device5",
      "isOnline": "1",
      "channel_id": "c127d*******d317c7b"
    },
    {
      "EPI": "2319955030",
      "topic": "c127d*******d317c7b/UAT/VC/2319955030/POS",
      "Label": "VL100#8",
      "isOnline": "0",
      "channel_id": "c127d*******d317c7b"
    }
  ]
}

Response fields — top level

Field	Type	Description
`code`	integer	HTTP status code (`200`)
`status`	string	`OK` on success
`devices`	array	Array of device status objects

`devices` — device status fields

Field	Type	Description
`EPI`	string	Terminal EPI identifier
`topic`	string	Partially masked MQTT topic used for Valor Connect communication with this device
`Label`	string	Terminal display label
`isOnline`	string	`1` if the device is currently online and reachable; `0` if offline
`channel_id`	string	Partially masked channel ID for the Valor Connect session

Response — 400 (Authentication Error)

{
  "status": "FAILED",
  "code": 400,
  "message": "Not a valid APP ID or APP Key."
}

Response fields

Field	Type	Description
`status`	string	`FAILED` when authentication fails
`code`	integer	HTTP status code (`400`)
`message`	string	Error message

Error code reference

`status`	Meaning	Typical cause
`OK`	Success	Device status list returned
`FAILED`	Authentication error	App ID or App Key is invalid

Valor Connect Device Status — Multi-MID

Retrieve the online/offline status of Valor Connect-enabled terminals for a Multi-MID merchant configuration. Returns the parent device along with its associated child EPIs.

Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "devices": [
    {
      "EPI": "2319938037",
      "topic": "c127d*******d317c7b/UAT/VC/2319938037/POS",
      "Label": "VL100#Mid",
      "isOnline": "0",
      "channel_id": "c127d*******d317c7b",
      "children": [
        {
          "child_epi": "2319938042",
          "child_label": "VL100#Mid"
        },
        {
          "child_epi": "2319938046",
          "child_label": "VL100#Mid"
        },
        {
          "child_epi": "2319940510",
          "child_label": "VL100#Mid"
        }
      ]
    }
  ]
}

Response fields — top level

Field	Type	Description
`code`	integer	HTTP status code (`200`)
`status`	string	`OK` on success
`devices`	array	Array of parent device status objects

`devices` — parent device fields

Field	Type	Description
`EPI`	string	Parent terminal EPI identifier
`topic`	string	Partially masked MQTT topic for the parent device
`Label`	string	Parent terminal display label
`isOnline`	string	`1` if the parent device is online; `0` if offline
`channel_id`	string	Partially masked channel ID for the Valor Connect session
`children`	array	Array of child EPI objects associated with this parent terminal (see below)

`children` — child EPI fields

Field	Type	Description
`child_epi`	string	Child terminal EPI identifier
`child_label`	string	Child terminal display label

Note: In a Multi-MID configuration, the parent device handles the physical connection while child EPIs represent the individual MID profiles. The isOnline status reflects the physical device state and applies to all associated child EPIs.

Response — 400 (Authentication Error)

{
  "status": "FAILED",
  "code": 400,
  "message": "Not a valid APP ID or APP Key."
}

Response fields

Field	Type	Description
`status`	string	`FAILED` when authentication fails
`code`	integer	HTTP status code (`400`)
`message`	string	Error message

Error code reference

`status`	Meaning	Typical cause
`OK`	Success	Multi-MID device status returned
`FAILED`	Authentication error	App ID or App Key is invalid

Publish API

Response — 200 OK (Approved)

Response — 200 OK (Cancelled / Timed Out)

Response fields — top level

response — approved transaction fields

TAXES object

response — cancelled / timed out fields

Response — 400 (Processing Error)

Response fields

Error code reference

Status API

Response — 200 OK (Approved)

Response — 400 (Processing Error)

Response fields

Error code reference

Cancel API

Response — 200 OK

Response fields

Response — 400 (Processing Error)

Response fields

Error code reference

Valor Connect Device Status

Response — 200 OK

Response fields — top level

devices — device status fields

Response — 400 (Authentication Error)

Response fields

Error code reference

Valor Connect Device Status — Multi-MID

Response — 200 OK

Response fields — top level

devices — parent device fields

children — child EPI fields

Response — 400 (Authentication Error)

Response fields

Error code reference

`response` — approved transaction fields

`TAXES` object

`response` — cancelled / timed out fields

`devices` — device status fields

`devices` — parent device fields

`children` — child EPI fields