Apidocs

Transaction Status Check API

Version History

Field	Description	End Points
05/08/25	Initial release of Transaction Status Check API (v1)	iposTransactStatus v1

Prerequisites

For Sandbox (UAT)

Users should be onboarded on the iPOSpays sandbox (UAT) environment as a merchant and have a valid TPN.

For Production (Live)

Users should be onboarded on the iPOSpays production environment as a merchant and have a valid TPN.

If you do not have a TPN, contact your ISO or support@dejavoo.io

Generate an Authentication Token

To authenticate your API requests, you must include a valid token in the request header. This token is generated directly from the merchant portal.

Steps to Generate a Token:

Step 1: Log in to your merchant account via the iPOSpays Portal and go to the Settings section.

Step 2: Under the Generate Ecom/TOP Merchant Keys section:

Select the appropriate TPN (Terminal Profile Number) from the dropdown list.
Click Generate Token to create a new authentication token.
The generated token will be displayed and must be used in your API request headers.

Need help? Watch this video tutorial for a guided walkthrough of the token generation process.

Endpoints and Request Method

Request Method: POST

Endpoints

Environment	URL
Sandbox	https://payment.ipospays.tech/api/v1/iposTransactStatus
Production	https://payment.ipospays.com/api/v1/iposTransactStatus

Request Parameters

Header

Field	Type	Description
token *	String	The authentication token required for all API requests. This token is generated from the iPOSpays Merchant Portal under the Settings > Generate Ecom/TOP Merchant Keys section. It authorizes the request and links it to a specific TPN (Terminal Profile Number).

Body

Field	Type	Description
merchantId *	String	Unique ID of the merchant
transactionReferenceId *	String	Unique reference ID of the original transaction for which the status inquiry is being made. This value must match the one used in the original payment request.

Response Parameters

Field	Type	Description
respCode	String	Response code returned by the processor (e.g., “00” for Approved).
appCode	String	Approval code assigned by the acquirer or gateway.
respMsg	String	Human-readable message describing the result of the transaction.
txRefNo	String	Unique transaction reference ID originally sent in the request.
dTxId	String	Unique transaction ID generated by the system.
hTxId	String	Host transaction ID, used for backend reconciliation.
batchNo	Integer	Batch number where the transaction is grouped.
invoiceNo	Integer	Invoice number associated with the transaction.
rrn	String	Retrieval reference number provided by the processor.
processingCode	String	Code indicating the type of transaction being processed.
hrc	String	Host Response Code.
respStatus	String	Transaction status (e.g., Approved, Declined).
amount	String	Base transaction amount.
tips	String	Tip amount included in the transaction, if any.
customFee	String	Custom fee amount applied, if applicable.
feeLabel	String	Label describing the custom fee.
localTax	String	Amount of local tax applied.
stateTax	String	Amount of state tax applied.
lTaxLabel	String	Label describing the local tax.
gTaxLabel	String	Label describing the state tax.
totalAmount	String	Total transaction amount including tax, tip, and fees.
txnSettleStatus	String	Indicates if the transaction is settled or pending (e.g., “Yet to Settle”).
transactionType	String	Type of transaction (e.g., SALE, REFUND, CHECK).
cardType	String	Type of card or wallet used.
achToken	String	(For ACH/Wallet) Encrypted token for ACH or wallet transaction.

Nested Objects

TxDetail

Field	Type	Description
DateNTime	String	Date and time when the transaction occurred. Format: YYYYMMDDHHMMSS.
Tpn	String	Terminal Profile Number associated with the transaction.

Card

Field	Type	Description
ChdToken	String	Encrypted token representing the cardholder data.
Label	String	Card brand (e.g., VISA, AMEX, MASTERCARD).
MaskedPan	String	Masked Primary Account Number (e.g., ** ** 1234).

Sample Request – Standard Card Transaction

Checks the status of a card-based transaction using the merchantId (TPN) and the unique transactionReferenceId generated at the time of payment.

Request Header

{
  "token": "" 
};

Request Body

{
  "merchantAuthentication": {
    "merchantId": "962923571839",
    "transactionReferenceId": "3245623463254631"
  }
}

Sample Response – Standard Card Transaction

Returns the transaction status and details such as approval code, transaction ID, batch number, amount breakdown (tip, tax, fees), and settlement status for a card-based transaction.

{
  "iposhpresponse": {
    "Response": {
      "RespCode": "00",
      "AppCode": "AXS009",
      "RespMsg": "Approved",
      "TxRefNo": "3245623463254631",
      "DTxId": "99454496548357183920250626112804",
      "HTxId": "000000321000010",
      "BatchNo": 993,
      "InvoiceNo": 9,
      "Rrn": "517705501432",
      "ProcessingCode": "000000",
      "HRC": "00",
      "RespStatus": "Approved",
      "Amount": "150",
      "Tips": "00",
      "CustomFee": "8",
      "FeeLabel": "Custom Fee",
      "LocalTax": "30",
      "StateTax": "15",
      "LTaxLabel": "Local Tax",
      "GTaxLabel": "State Tax",
      "TotalAmount": "203",
      "TxnSettleStatus": "Yet to Settle",
      "TransactionType": "SALE"
    },
    "TxDetail": {
      "DateNTime": "20250626112804",
      "Tpn": "962923571839"
    },
    "Card": {
      "ChdToken": "5502127CC0140E22C6E30808D971BB9113E760DC3F3C2366",
      "Label": "AMEX",
      "MaskedPan": "3796056666"
    }
  }
}

Sample Request – Alternate Payment (Wallet/ACH)

Used to check the status of non-card transactions like ACH or digital wallets, by passing the same merchantId and transactionReferenceId.

Request Header

{
  "token": "" 
};

Request Body

{
  "merchantAuthentication": {
    "merchantId": "962923571839",
    "transactionReferenceId": "9298395654Testing024122"
  }
}

Sample Response – Alternate Payment

Provides status and transaction details for ACH or wallet payments, including approval message, ACH token, amount, type (e.g., CHECK), and whether the transaction is settled.

{
  "iposhpresponse": {
    "Response": {
      "RespCode": "00",
      "RespMsg": "APPROVAL - AUTH NUM 272-172",
      "TxRefNo": "9298395654Testing024122",
      "DTxId": "28118655670253241411750855554528",
      "BatchNo": "607",
      "Rrn": "-rosY2zcUJilI0i2-_uVcDAYaJdZWMItJmrq",
      "TotalAmount": "1231",
      "Amount": "1231",
      "Tip": "0",
      "CardType": "Wallet",
      "TransactionType": "CHECK",
      "Status": "Approved",
      "AchToken": "05944FB3E1DA4663868455AF630F45BE",
      "TxnSettleStatus": "Yet to Settle"
    },
    "TxDetail": {
      "DateNTime": "11750855554528",
      "Tpn": "567025324141"
    }
  }
}

Sample Error Response – Invalid Transaction Reference

Returned when the transactionReferenceId is invalid or not found. Includes an error message indicating no transaction was registered with the provided reference ID.

Request

Request Header

{
  "token": "" 
};

Request Body

{
  "merchantAuthentication": {
    "merchantId": "962923571839",
    "transactionReferenceId": "3245623463254631S2343W12345354356"
  }
}

Response

{
  "errors": [
    {
      "field": "IPOSTRANCT_001",
      "message": "No Transaction Registered with This TransactionRefId. Please try with valid details.",
      "bulbIconRequired": false
    }
  ]
}

Notes

The field TxnSettleStatus indicates whether the transaction has been settled or is still pending.
The response structure varies slightly based on whether it is a card or an alternate payment method.
Ensure that the transactionReferenceId used is the same one provided at the time of initiating the transaction.

Transaction Status Check Error Codes and Messages