This is a test environment for documentation.
iPOS Transact
API Docs

iPOS Transact API

Version History

DateDetailsEnd Points
30/09/22 Initial releaseiPOS Transact V1 and above
30/05/24 Version 2 - AVS ObjiPOS Transact V2 and above
20/08/24 Ticket, Tip Adjust - transaction typeiPOS Transact V2 and above
28/01/25 Google payiPOS Transact V2 and above
29/04/25 Paya TokeniPOS Transact V2 and above
08/05/25 ACH TokeniPOS Transact V2 and above
13/05/25 HSA card FeaturesiPOS Transact V2 and above
21/05/25 Version 3 - Encrypted Card DataiPOS Transact V3

Note: Please use the V3 endpoint to send encrypted card data and to perform actions such as sale, refund, void, and other transactions.

Prerequisites

  • For Sandbox (UAT)

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

  • For Production (Live)

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

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

How to Generate an Auth Token

  • Step 1 : Login to your merchant account and go to settings.

  • Step 2 : Under the Generate Ecom/TOP Merchant Keys section, search for and select your TPN from the drop-down menu and click Generate Token.

Supported Transaction Types

The iPOS Transact API allows you to perform the following transactions:

  • Sale - A sale transaction is a regular transaction where the entered amount is processed and sent to the processor after the batch has been settled.

  • Pre Auth - A Pre Auth transaction allows the user to temporarily reserve a specific amount of money for a transaction.

  • Void - A Void transaction is used to cancel a previously authorized transaction before the batch is closed and sent to the processor.

  • Refund - A Refund transaction is used to refund the amount back to the customer after the batch has been settled. The refund amount is then sent to the processor.

  • Ticket - A Ticket transaction is used to retrieve and process the amount that was temporarily held in the Pre Auth transaction.

  • Tip Adjust - Tip Adjust enables users to modify the tip amount on a transaction before the batch is settled and sent to the processor.

  • Incremental Auth - Incremental Authorization allows merchants to easily adjust a Pre Auth transaction when a customer exceeds the initial amount, without having to void and reprocess the transaction.

  • Open Batch - An Open Batch allows merchants to view all transactions, review the batch summary, and void transactions before they are settled and sent to the processor.

  • Batch Settlement - Batch settlement is the process of consolidating and submitting all authorized transactions at the end of the business day to the payment processor. This ensures timely reconciliation and transfer of funds to the merchant’s bank account.

How to Use iPOS Transact API

For Sale / Pre-Auth Transactions

To perform a Sale or Pre-Authorization using the iPOS Transact API, you must include a Card Token, also called an iPOS Token.

  • This token represents the card details in a secure format.

  • You can generate the token by using either of the following APIs:

HPP APISPIn API

"Card Token" and "iPOS Token" mean the same thing in this context.

For Void / Refund Transactions

If you're using the iPOS Transact API only for void or refund operations:

  • HPP or SPIn integration is not required.

  • Simply pass the original transaction’s RRN number in the request.

For ACH Transactions

To process ACH transactions via the iPOS Transact API, choose one of the two methods based on your integration approach:

1. Using the ACH Token from the HPP API

For merchants using the Hosted Payment Page (HPP), an ACH token is returned upon a successful initial ACH submission. This token can be used to perform subsequent ACH transactions without re-entering banking details.

✅ Best for merchants leveraging the HPP for seamless and secure data collection.

HPP API

2. Using Individual Bank Account Tokens (Freedom to Design - FTD)

For merchants using Freedom to Design (FTD) to build their own UI, ACH transactions must be processed using the iPOS Transact API. You'll need to collect and tokenize individual bank details (account number, routing number, etc.) and send them as part of the ACH request.

⚠️ This method applies only to those using FTD. All ACH transactions in FTD must be processed through the iPOS Transact API.

HPP API

End Points and Objects

Request Method

HTTPS Request MethodPOST

End Points

Version 3 (Use v3 End Points)

ObjectsDescription
Sandbox URL * https://payment.ipospays.tech/api/v3/iposTransact
Production URL * https://payment.ipospays.com/api/v3/iposTransact

Version 2

ObjectsDescription
Sandbox URL * https://payment.ipospays.tech/api/v2/iposTransact
Production URL * https://payment.ipospays.com/api/v2/iposTransact

Version 1

ObjectsDescription
Sandbox URL * https://payment.ipospays.tech/api/v1/iposTransact
Production URL * https://payment.ipospays.com/api/v1/iposTransact

Request Parameters - Header Objects

ObjectsDescription
token AuthToken (can be obtained from portal settings).
JSON Content-Type application/json

Request Parameters - Body Objects

ObjectsUsage ConditionDescription
merchantAuthentication RequiredIncludes merchant authentication details, such as the TPN number and unique transaction reference ID.
transactRequest RequiredContains details such as transaction type, card token, amount, fee calculation, etc.
preferences RequiredSpecifies whether AVS (Address Verification Service) verification is needed or if an e-receipt should be sent via SMS/email to the end user.
AVS RequiredProvides AVS details, including street number and ZIP code.
FieldTypeUsage ConditionDescription
merchantAuthentication ( Obj )
merchantId * Number Required

TPN number registered on the portal.

Example Value: 139322815010

Length: 12 digits

transactionReferenceId * string Required

Merchant's unique transaction reference ID.

Format: Alphanumeric

Length: Must be 20 characters or fewer.

transactRequest ( Obj )
amount * String Required

Amount (in USD) to be charged. Multiply the USD amount by 100.

Length: 8 characters

Format: 12525 (e.g., $125.25 × 100).

RRN * Number Conditional

Unique retrieval reference number.

Length: 12 characters

Conditional: Required only for Void, Refund, Ticket & Tip Adjust.

transactionType * Number Required

Type of transaction to be processed.

Default: 1

Values:

1 – Sale (using card token)

5 – PreAuth (using card token).

10 - ACH (using achToken)

cardToken* * String Required

Tokenized card value/string used to capture the specified amount for the tokenized card.

Format: Encrypted token string.

paymentTokenId * String Conditional

Tokenized payment value/string used to capture the specified amount for the tokenized card. (Applicable only for Sale transactions.)

Format: Encrypted token string.

applySteamSettingTipFeeTax * String Required

Determines if tips, fees, and taxes should be calculated based on what is configured in S.T.E.A.M → Edit Parameter and add to the base amount to charge the customer.

Values: true or false

Default: false

Note:

If set to true: The iposTransact API will calculate tips, fees, and taxes based on S.T.E.A.M parameters and add them to the base amount.

If set to false: The iposTransact API will treat the amount in the request payload as the total amount.

achToken String Optional

Tokenized string used to capture the specified account information to process the ACH Services. (Applicable only for Sale-ACH transactions.)

Format: Unique token string

achTransactionId String Optional

achTransactionId will be provided in Sale-ACH Response where we need to use this String to complete the Void/Refund Transaction for ACH if client to Cancel the transaction

Format : Transaction Id String

achProccessor Number Optional

achProcessor will provide whether you are trying to perform the transaction with PAYA Token or other Processor Token

Format : 1 - PAYA

preferences ( Obj )
eReceipt * Boolean Required

To send payment status notifications to customers via SMS and/or email.

Values: true or false.

customerName String Optional

The customer’s email address to which payment status will be sent if requested.

Format: Alphabets and spaces

Length: Up to 25 characters

Note: This field is required if eReceipt is set to true.

customerEmail String Optional

Customer e-mail id to which payment status will be notified if requested

Format: Valid email address

Note: This field is required if eReceipt is set to true.

customerMobile String Optional

Customer mobile number to which payment status will be sent if requested.

Format: +<country-code><number>

Example: +18989898989

Length: 13 characters

Note: This field is required if eReceipt is set to true.

requestCardToken Boolean Optional

Indicates whether to send tokenized card details to the integrator for the requested customer.

Values: true or false.

GooglePay Object Optional

Encrypted Request Received from Google under Dejavoo PSP Key.

Values : Encrypted Data from Google

Note : If GooglePay Object is passed then PaymentTokenId and CardToken should be null

requestAchToken Boolean Optional

Indicates whether to send ACH card details to the integrator for the requested customer.

encryptedCardData (Use v3 Version) String Optional

This Field contains the encrypted Card Information which will be encrypted by public Key shared from Dejavoo. And the format will be shared in Link.

AVS ( Obj - Use v2 version )
StreetNo String Optional

Street number of the customer's address.

Zip String Optional

Zip code of the customer’s address.

HSA ( Obj - HSA Cards Need to Process this Information )
HSA_TotalAmount String Optional

Total amount to be debited from the HSA card.Format: Multiply value by 100 (e.g., 1200 = $12.00 → 12 * 100)

HSA_RxAmount String Optional

Amount for prescriptions covered by HSA.Format: Multiply value by 100 (e.g., 200 = $2.00 → 2 * 100)

HSA_DentalAmount String Optional

Amount for dental specialist services.Format: Multiply value by 100 (e.g., 100 = $1.00 → 1 * 100)

HSA_ClinicAmount String Optional

Amount for general clinical services.Format: Multiply value by 100 (e.g., 100 = $1.00 → 1 * 100)

HSA_VisionAmount String Optional

Amount for optical/eye care services.Format: Multiply value by 100 (e.g., 100 = $1.00 → 1 * 100)Note: If opticalAmount is present, do not include totalAmount, prescriptionAmount, dentalAmount, or clinicAmount.

ACH ( Obj - This is only for processing original transaction not for achToken from HPP API )
firstName String Conditional

The first name of the individual associated with the bank account or transaction. This is often used for identity verification. Tagged with below div : <div id=''FIRST_NAME''></div>

lastName String Conditional

The last name of the individual associated with the bank account or transaction, also crucial for identity verification. Tagged with below div : <div id=''LAST_NAME''></div>

phoneNumber String Conditional

The primary contact phone number of the individual or entity initiating or receiving the ACH transaction. This field is often used for:

- Identity Verification (KYC/AML): As a data point for confirming the identity of the account holder.

- Transaction Notifications: To send alerts or confirmations regarding the transaction status.

- Fraud Prevention: To contact the user in case of suspicious activity or to perform additional verification.

- Customer Service: For support inquiries related to the transaction.

Its ''Conditional'' usage means it may not always be strictly required for the ACH processing itself, but is often highly recommended or mandated by your platform's risk management or compliance policies, or by specific regulations like Nacha rules for certain entry classes (e.g., TEL). <div id=''PHONE_NUMBER''></div>

addressOne String Conditional

The primary street address (e.g., street number and name) of the individual or entity. Used for verification and compliance. Tagged with below div : <div id=''ADDRESS''></div>

Email String Conditional

The email address of the individual or entity associated with the ACH transaction. This field is commonly used for:

- Transaction Notifications: To send confirmations, receipts, or status updates regarding the ACH transfer.

- Identity Verification (KYC/AML): As a data point to help verify the identity of the account holder.

- Communication: For customer support, dispute resolution, or to provide important information related to the transaction.

- Account Management: Linking the transaction to a user's profile within a system.

While not always a direct requirement for the ACH network itself, it is frequently a "Conditional" field mandated by the originating platform or financial institution for communication, security, and compliance purposes. <div id=''EMAIL''></div>

state String Conditional

The state of residence or business for the individual or entity. Typically represented by a two-letter abbreviation (e.g., CA, NY). Tagged with below div : <div id=''STATE''></div>

dlNumber String Conditional

Driver's License Number. This field is likely used for identity verification or Know Your Customer (KYC) requirements, especially for consumer-initiated ACH debits. Tagged with below div : <div id=''DL_NUMBER''></div>

dlState String Conditional

The state that issued the Driver's License. This helps to confirm the validity of the dlNumber. Tagged with below div : <div id=''DL_STATE''></div>

accountNumber String Mandatory

The bank account number for the ACH transaction. This is the unique identifier for the specific bank account to be debited or credited. This is a mandatory field for any ACH transaction. Tagged with below div : <div id=''ACCOUNT_NUMBER''></div>

accountType String Mandatory

The type of bank account, typically either ''Checking'' or ''Savings''. This is crucial for correctly processing the ACH transaction. Tagged with below div : <div id=''ACCOUNT_TYPE''></div>

routingNumber String Mandatory

The bank routing number (ABA Transit Number). This nine-digit number identifies the financial institution where the account is held. This is a mandatory field for any ACH transaction. Tagged with below div : <div id=''ROUTING_NUMBER''></div>

ssn String Conditional

Social Security Number. A critical piece of information for identity verification and compliance with financial regulations, particularly for consumer transactions. Often only the last four digits are required depending on the use case and compliance level. Tagged with below div : This needs to be added only if the identity flag is set to true. <div id=''SSN''/>

dobYear String Conditional

The date of birth of the individual. A key piece of information for identity verification and age validation, often required for KYC compliance. Tagged with below div : This need to added based on identity flag should come as true <div id=''DOB''/>

city String Conditional

The city of residence or business for the individual or entity. Used in conjunction with street address, state, and zip code for full address verification. Tagged with below div : <div id=''CITY''></div>

zipCode String Conditional

The postal code (ZIP code in the U.S.) for the individual's or entity's address. Essential for address validation and location-based checks. Tagged with below div : <div id=''ZIP''></div>

identity String Mandatory

A boolean flag (true/false) indicating whether the identity of the account holder has been successfully verified. This is crucial for compliance (e.g., KYC/AML) before an ACH transaction can proceed. Tagged with below div : <div id=''IDENTITY''></div>

terminalId String Mandatory

A unique identifier for the specific terminal, device, or point of origin from which the ACH transaction was initiated. This is important for tracking, auditing, and often for fraud prevention. Tagged with below div :

entryClass String Mandatory

The ACH Entry Class Code. This three-letter code defines the type of ACH transaction being processed (e.g., PPD for Prearranged Payment and Deposit, CCD for Corporate Credit or Debit, WEB for Internet-Initiated Entry, TEL for Telephone-Initiated Entry, etc.). It dictates specific rules and formatting for the transaction. Tagged with below div :

usersId String Mandatory

A unique identifier for the user initiating or associated with the ACH transaction within your system. This is crucial for linking transactions to specific users, for auditing, and for managing user accounts. Tagged with below div :

tipAmount String Conditional

The amount of a tip or gratuity, if applicable, associated with the transaction. This field is ''Conditional'' because not all transactions will include a tip. If present, it would be added to the base transaction amount. Tagged with below div :

Response Parameters

FieldTypeUsage ConditionDescription
iPOS-TransactResponse ( Obj )
responseCode * Number Required

iPOS-Transact response code.

Values:

200 – Successful, 400 – Declined

responseMessage * string Required

iPOS-Transact response message.

Values: Successful, Declined

errResponseCode* * Alphanumeric Conditional

PG error response code.

Values: PG error response code or payment processor error response code.

Length: Up to 2 characters

Example: 00, 05, …

errResponseMessage* * string Conditional

PG error response message.

Values: PG error response message or payment processor error response message.

transactionReferenceId * string Required

Merchant's unique transaction reference ID.

Format: Alphanumeric

Length: Up to 20 characters

transactionType * Number Required

Type of transaction to be processed.

Values:

1 – Sale

2 – Void

3 – Refund

amount Float Required

Amount voided/refunded.

Format: xxxxxx.xx

responseApprovalCode string Optional

Response Approval Code.

Format: Alphanumeric

Length: 6 characters

RRN Number Required

Unique retrieval reference number.

Length: 12 characters

transactionId * Number Required

PG response unique transaction ID.

Length: 32 characters

transactionNumber Number Optional

Invoice or transaction number.

Length: 4 digits

batchNumber Number Optional

Batch number.

Length: 3 digits

totalAmount Float Optional

Total amount charged to the customer.

Format: xxxxxx.xx

Length: Up to 8 characters

customFee Float Optional

Custom fee charged to the customer.

Format: xxxxxx.xx

chdToken String Optional

Tokenized card data, sent in response if the requestCardToken field is set to true in the request.

Format: Alphanumeric

total_without_fee * Decimal Required

Total Amount without Fee

Values: 1.00

batch_number * String Required

Batch Number for Settlement Batch

Values: 423

batch_profiles Object Optional

Batch Profiles Data

withoutLocalTaxAmount Decimal Optional

Total Amount without Local Tax

Values: 1.00

without_tax Decimal Optional

Total Amount without Tax

Values: 1.00

batch_summary Object Optional

Batch Summary Information

inx String Optional

Batch Summary Index

Value : 1

amount Decimal Optional

Total Batch Settlement Amount

Value : 96.94

profileId String Optional

Profile Number Register with TPN

Value: 01

type * String required

Type of Transaction

Value: SALE

txName String Optional

Type of Transaction

Value: SALE

transaction_no Number Optional

Transaction Number

Value : 2

batch_number String Optional

Batch Number

Value : 2

fee Decimal Optional

Fee Amount

Value : 3.63

batch_details Object Optional

Batch Detail Information

surcharge Number Optional

Surcharge

reducedTaxFee String Optional

Reduced Tax Fee

groupType String Optional

Group Type

approvalCode String Optional

Transaction Approval Code

Value : TAS996

externalRefId String Optional

External Transaction Id

tagValue String Optional

Tag Value

discount Number Optional

Discount Amount

appCode String Optional

Transaction Approval Code

Value : TAS996

type String Optional

Transaction Type

Value : Sale

voidFlag String Optional

Void Status

Value : N/Y

posRequestTime String Optional

Transaction Request Time

invoiceNumber String Optional

Invoice Number

onlyTipAmt Number Optional

Tip Amount

customFee Number Optional

Custome Fee

approvedAmount Decimal Optional

Approved Txn Amount

commercialTaxAmount Number Optional

Commercial Tax Amount

reducedTax Number Optional

Reduced Tax Amount

tagLabel String Optional

Tag Label Value

serviceFee Decimal Optional

Service Fee Amount

amount Decimal Optional

Transaction Amount

tipAmount Decimal Optional

Tip Amount

merchantFee Decimal Optional

Merchant Fee

transactionId String Optional

Unique Transaction generated per Request

stateTaxAmount Decimal Optional

State Tax Amount

baseAmount Decimal Optional

Base Amount

rrn String Optional

Transaction Unique Number

localTaxAmount Decimal Optional

Local Tax Amount

feeAmount Decimal Optional

Fee Amount

profileId String Optional

Profile Id

adjustedTipAmount Decimal Optional

Adjusted Tip Amount

totalTaxAmount Decimal Optional

Total Tax Amount

posRequestDate String Optional

Pos Request Date

account String Optional

Transaction Initiated PAN

card String Optional

Card Type

discount Decimal Optional

Discount Amount

settleDate String Optional

Settled Date

batchBase Decimal Optional

Batch Base Amount

Batch Total Amount Decimal Optional

Discount Amount

stateTaxAmount Decimal Optional

State Tax Amount

withoutStateTaxAmount Decimal Optional

Without State Tax Amount

localTaxAmount Decimal Optional

Local Tax Amount

without_discount Decimal Optional

Without Discount

profile_name String Optional

Profile Name

without_tip String Optional

Without Tip Amount

profileCode String Optional

Profile Code

tip Decimal Optional

Tip Amount

without_fee Decimal Optional

Without Fee Amount

taxAmount Decimal Optional

Tax Amount

transaction_no Number Optional

Transaction Number

processorData Object Optional

Processor Information

Agent String Optional

Agent Number

Chain String Optional

Chain Number

TermNo String Optional

Terminal Number

Agent_FIID String Optional

Agent Id

Mid String Optional

Terminal Registered under Merchant Number

Store String Optional

Registered Store Number

dsGroup String Optional

Terminal Number

TermId String Optional

Registered under Bank

ABA_No String Optional

Bank routing number

total_transactions Number Optional

Number of transaction Settle

total_fee Decimal Optional

Total Fee Amount

cash_payment Object Optional

Cash Payment Transactions

data Object Optional

Cash Payment Transactions Data

cash_payment_total Number Optional

Total Cash Payments

cash_txn_count Number Optional

Total Cash Txn Count

alter_payments Object Optional

Alter Payment under TPN

alter_txn_count Number Optional

Alter Payment Txn Count

approvalCode String Optional

Approval Code

txTime String Optional

Transaction Time

DiscountFee Decimal Optional

Discount Fee

createdAt String Optional

Transaction Requested Date

posResponseCode String Optional

Pos Response Code

invoiceNumber String Optional

Invoice Number

onlyTipAmt Decimal Optional

Tip Amount

cashDiscount Decimal Optional

Cash Discount Amount

txName String Optional

Transaction Name

updatedAt String Optional

Transaction Response Updated Date

serviceFee String Optional

Service Fee Amount

hostResponseCode String Optional

Host Response Code

maskedPan String Optional

Masked PAN number

additionalDetails String Optional

Additional Details

transactionId String Optional

Transaction Id generated per request

destType String Optional

Destination Name

txAmount Decimal Optional

Transaction Amount

rrn String Optional

Unique Transaction Number from Processor

transactionType Decimal Optional

Type of Transaction

totalAmount Decimal Optional

Total Amount

tpn String Optional

Merchant Id

sourceType String Optional

Requested Source Name

commonMode String Optional

Mode of Request Received

txDate String Optional

Transaction Date

alter_payment_total Decimal Optional

Alter Payments Total Amount

total_tip Decimal Optional

Total Tip Amount

batch_total Decimal Optional

Batch Total Amount

Sample Requests and Responses for Card

SALE

SALE - cardToken (Use v1 End Points)
Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": 1, // Sale (using token)
        "amount": "", // Example: 1000 = $10.00 (amount is in cents, divided by 100)
        "cardToken": "", // Transactions initiated from iPOS Transact API (Optional for GooglePay and PaymentTokenId)
        "applySteamSettingTipFeeTax": true/false
    },
    "preferences": {
        "eReceipt": true/false,
        "customerName": "Customer_Name",
        "customerEmail": "Customer_Email",
        "customerMobile": "Customer_mobile_number_with_ISD_code"
    },
    "Avs": {
        "StreetNo": "23453",
        "Zip": "12344"
    },
    "GooglePay": paymentData
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response
{
    "iposTransactResponse": {
        "responseCode": "iPOS-HP response code like 200, 400, ...",
        "responseMessage": "Successful/Declined",
        "errResponseCode": "Error response code",
        "errResponseMessage": "Error response message",
        "transactionReferenceId": "merchant unique transaction reference id sent on request",
        "transactionType": 1, // Sale
        "transactionId": "Unique transaction Id of payment processor",
        "transactionNumber": "4 digits of transaction number from payment processor",
        "batchNumber": "3 digits of batch number from payment processor",
        "amount": "base amount or total amount charged",
        "customFee": "custom fee",
        "totalAmount": "total amount charged",
        "responseApprovalCode": "response approval code from processor ex: TAS164",
        "RRN": "retrieval reference number from processor #219313501821"
    }
}
SALE - paymentTokenId (Use v1 End Points)
Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": 1, // Sale (using token)
        "amount": "", // Example: 1000 = $10.00 (amount is in cents, divided by 100)
        “paymentTokenId”: "", // Transactions initiated from Freedom to Design (Optional for GooglePay)
        "applySteamSettingTipFeeTax": true/false
    },
    "preferences": {
        "eReceipt": true/false,
        "customerName": "Customer_Name",
        "customerEmail": "Customer_Email",
        "customerMobile": "Customer_mobile_number_with_ISD_code"
    },
    "Avs": {
        "StreetNo": "23453",
        "Zip": "12344"
    },
    "GooglePay": paymentData
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response
{
    "iposTransactResponse": {
        "responseCode": "iPOS-HP response code like 200, 400, ...",
        "responseMessage": "Successful/Declined",
        "errResponseCode": "Error response code",
        "errResponseMessage": "Error response message",
        "transactionReferenceId": "merchant unique transaction reference id sent on request",
        "transactionType": 1, // Sale
        "transactionId": "Unique transaction Id of payment processor",
        "transactionNumber": "4 digits of transaction number from payment processor",
        "batchNumber": "3 digits of batch number from payment processor",
        "amount": "base amount or total amount charged",
        "customFee": "custom fee",
        "totalAmount": "total amount charged",
        "responseApprovalCode": "response approval code from processor ex: TAS164",
        "RRN": "retrieval reference number from processor #219313501821"
    }
}
SALE - encryptedCardData (Use v3 End Points)
Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": 1, // Sale (using token)
        "amount": "", // Example: 1000 = $10.00 (amount is in cents, divided by 100)
        “encryptedCardData”: "", // Transactions initiated from iPOS Transact API (Optional for GooglePay, ApplePay, PaymentTokenId, CardToken)
        "applySteamSettingTipFeeTax": true/false
    },
    "preferences": {
        "eReceipt": true/false,
        "customerName": "Customer_Name",
        "customerEmail": "Customer_Email",
        "customerMobile": "Customer_mobile_number_with_ISD_code"
    },
    "Avs": {
        "StreetNo": "23453",
        "Zip": "12344"
    }
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response
{
    "iposTransactResponse": {
        "responseCode": "iPOS-HP response code like 200, 400, ...",
        "responseMessage": "Successful/Declined",
        "errResponseCode": "Error response code",
        "errResponseMessage": "Error response message",
        "transactionReferenceId": "merchant unique transaction reference id sent on request",
        "transactionType": 1, // Sale
        "transactionId": "Unique transaction Id of payment processor",
        "transactionNumber": "4 digits of transaction number from payment processor",
        "batchNumber": "3 digits of batch number from payment processor",
        "amount": "base amount or total amount charged",
        "customFee": "custom fee",
        "totalAmount": "total amount charged",
        "responseApprovalCode": "response approval code from processor ex: TAS164",
        "RRN": "retrieval reference number from processor #219313501821"
    }
}

iPOS Transact API – Sale transaction Using Token (Postman Simulator URL)

Version 3 (Use v3 End Points)

ObjectsDescription
Sandbox URL * https://payment.ipospays.tech/api/v3/iposTransact
Production URL * https://payment.ipospays.com/api/v3/iposTransact

Version 2

ObjectsDescription
Sandbox URL * https://payment.ipospays.tech/api/v2/iposTransact
Production URL * https://payment.ipospays.com/api/v2/iposTransact

Version 1

ObjectsDescription
Sandbox URL * https://payment.ipospays.tech/api/v1/iposTransact
Production URL * https://payment.ipospays.com/api/v1/iposTransact

PRE AUTH

PRE AUTH - cardToken (Use v1 End Points)
Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": 5, // Pre-Auth (using token)
        "amount": "", // Example: 1000 = $10.00 (amount is in cents, divided by 100)
        "cardToken": "", // Transactions initiated from iPOS Transact API (Optional for GooglePay and PaymentTokenId)
        "applySteamSettingTipFeeTax": true/false
    },
    "preferences": {
        "eReceipt": true/false,
        "customerName": "Customer_Name",
        "customerEmail": "Customer_Email",
        "customerMobile": "Customer_mobile_number_with_ISD_code"
    },
    "Avs": {
        "StreetNo": "23453",
        "Zip": "12344"
    },
    "GooglePay": "<GooglePay-Token>"
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response
{
    "iposTransactResponse": {
        "responseCode": "iPOS-HP response code like 200, 400, ...",
        "responseMessage": "Successful/Declined",
        "errResponseCode": "Error response code",
        "errResponseMessage": "Error response message",
        "transactionReferenceId": "merchant unique transaction reference id sent on request",
        "transactionType": 5, // Pre-Auth
        "transactionId": "Unique transaction Id of payment processor",
        "transactionNumber": "4 digits of transaction number from payment processor",
        "batchNumber": "3 digits of batch number from payment processor",
        "amount": "base amount or total amount charged",
        "customFee": "custom fee",
        "totalAmount": "total amount charged",
        "responseApprovalCode": "response approval code from processor ex: TAS164",
        "RRN": "retrieval reference number from processor #219313501821"
    }
}
PRE AUTH - paymentTokenId (Use v1 End Points)
Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": 5, // Pre-Auth (using token)
       "amount": "", {
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": 5, // Pre-Auth (using token)
        "amount": "", // Example: 1000 = $10.00 (amount is in cents, divided by 100)
               “encryptedCardData”: "", // Transactions initiated from iPOS Transact API (Optional for GooglePay, ApplePay, PaymentTokenId, CardToken)
 
 
        "applySteamSettingTipFeeTax": true/false
    },
    "preferences": {
        "eReceipt": true/false,
        "customerName": "Customer_Name",
        "customerEmail": "Customer_Email",
        "customerMobile": "Customer_mobile_number_with_ISD_code"
    },
    "Avs": {
        "StreetNo": "23453",
        "Zip": "12344"
    },
    "GooglePay": "<GooglePay-Token>"
}
 
        "paymentTokenId": "", // Transactions initiated from Freedom to Design (Optional for GooglePay)
        "applySteamSettingTipFeeTax": true/false
    },
    "preferences": {
        "eReceipt": true/false,
        "customerName": "Customer_Name",
        "customerEmail": "Customer_Email",
        "customerMobile": "Customer_mobile_number_with_ISD_code"
    },
    "Avs": {
        "StreetNo": "23453",
        "Zip": "12344"
    },
    "GooglePay": "<GooglePay-Token>"
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response
{
    "iposTransactResponse": {
        "responseCode": "iPOS-HP response code like 200, 400, ...",
        "responseMessage": "Successful/Declined",
        "errResponseCode": "Error response code",
        "errResponseMessage": "Error response message",
        "transactionReferenceId": "merchant unique transaction reference id sent on request",
        "transactionType": 5, // Pre-Auth
        "transactionId": "Unique transaction Id of payment processor",
        "transactionNumber": "4 digits of transaction number from payment processor",
        "batchNumber": "3 digits of batch number from payment processor",
        "amount": "base amount or total amount charged",
        "customFee": "custom fee",
        "totalAmount": "total amount charged",
        "responseApprovalCode": "response approval code from processor ex: TAS164",
        "RRN": "retrieval reference number from processor #219313501821"
    }
}
PRE AUTH - encryptedCardData (Use v3 End Points)
Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": 5, // Pre-Auth (using token)
        "amount": "", // Example: 1000 = $10.00 (amount is in cents, divided by 100)
        “encryptedCardData”: "", // Transactions initiated from iPOS Transact API (Optional for GooglePay, ApplePay, PaymentTokenId, CardToken)
        "applySteamSettingTipFeeTax": true/false
    },
    "preferences": {
        "eReceipt": true/false,
        "customerName": "Customer_Name",
        "customerEmail": "Customer_Email",
        "customerMobile": "Customer_mobile_number_with_ISD_code"
    },
    "Avs": {
        "StreetNo": "23453",
        "Zip": "12344"
    }
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response
{
    "iposTransactResponse": {
        "responseCode": "iPOS-HP response code like 200, 400, ...",
        "responseMessage": "Successful/Declined",
        "errResponseCode": "Error response code",
        "errResponseMessage": "Error response message",
        "transactionReferenceId": "merchant unique transaction reference id sent on request",
        "transactionType": 5, // Pre-Auth
        "transactionId": "Unique transaction Id of payment processor",
        "transactionNumber": "4 digits of transaction number from payment processor",
        "batchNumber": "3 digits of batch number from payment processor",
        "amount": "base amount or total amount charged",
        "customFee": "custom fee",
        "totalAmount": "total amount charged",
        "responseApprovalCode": "response approval code from processor ex: TAS164",
        "RRN": "retrieval reference number from processor #219313501821"
    }
}

iPOS Transact API – Sale transaction Using Token (Postman Simulator URL)

URLhttps://documenter.getpostman.com/view/21863361/2s83tCKYRA (opens in a new tab)

VOID

Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": <2-void>, 
        "rrn": "<rrn Number>", // RRN number received for original Transaction
        "amount": "" // Example: 1000 = $10.00 (amount is in cents, divided by 100)
    }
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response - Upon transaction success or decline
{
    "iposTransactResponse": {
        "responseCode": "iPOS-HP response code like 200, 400",
        "responseMessage": "Successful/Declined",
        "errResponseCode": "Error response code from PG",
        "errResponseMessage": "Error response message from PG",
        "transactionReferenceId": "merchant unique transaction reference id sent on request",
        "transactionType": "2 - void",
        "transactionId": "Unique transaction Id of PG",
        "amount": "amount or total amount refunded",
        "responseApprovalCode": "response approval code from processor ex: TAS164",
        "rrn": "retrieval reference number from processor #219313501821",
        "transactionNumber": "4 digits of transaction invoice number from processor",
        "batchNumber": "3 digits of batch number from processor"
    }
}

iPOSTransact API – (Postman) Simulator URL

URLhttps://documenter.getpostman.com/view/21863361/2s83tCKYRA (opens in a new tab)

REFUND

Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": <3-refund>,
        "rrn": "<rrn Number>", // RRN number received for original Transaction
        "amount": "" // Example: 1000 = $10.00 (amount is in cents, divided by 100)
    }
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response - Upon transaction success or decline
{
    "iposTransactResponse": {
        "responseCode": "iPOS-HP response code like 200, 400",
        "responseMessage": "Successful/Declined",
        "errResponseCode": "Error response code from PG",
        "errResponseMessage": "Error response message from PG",
        "transactionReferenceId": "merchant unique transaction reference id sent on request",
        "transactionType": "3 - refund",
        "transactionId": "Unique transaction Id of PG",
        "amount": "amount or total amount refunded",
        "responseApprovalCode": "response approval code from processor ex: TAS164",
        "rrn": "retrieval reference number from processor #219313501821",
        "transactionNumber": "4 digits of transaction invoice number from processor",
        "batchNumber": "3 digits of batch number from processor"
    }
}

iPOSTransact API – (Postman) Simulator URL

URLhttps://documenter.getpostman.com/view/21863361/2s83tCKYRA (opens in a new tab)

TICKET

Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": <6-ticket>,
        "rrn": "<rrn Number>", // RRN number received for original Transaction
        "amount": "" // Example: 1000 = $10.00 (amount is in cents, divided by 100)
    }
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response - Upon transaction success or decline
{
    "iposTransactResponse": {
        "responseCode": "iPOS-HP response code like 200, 400",
        "responseMessage": "Successful/Declined",
        "errResponseCode": "Error response code from PG",
        "errResponseMessage": "Error response message from PG",
        "transactionReferenceId": "merchant unique transaction reference id sent on request",
        "transactionType": "6 - ticket",
        "transactionId": "Unique transaction Id of PG",
        "amount": "amount or total amount refunded",
        "responseApprovalCode": "response approval code from processor ex: TAS164",
        "rrn": "retrieval reference number from processor #219313501821",
        "transactionNumber": "4 digits of transaction invoice number from processor",
        "batchNumber": "3 digits of batch number from processor"
    }
}

iPOSTransact API – (Postman) Simulator URL

URLhttps://documenter.getpostman.com/view/21863361/2s83tCKYRA (opens in a new tab)

TIP ADJUST

Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": <7-tipadjust>,
        "rrn": "<rrn Number>", // RRN number received for original Transaction
        "amount": "" // Amount to be TipAdjust example 1000 for $10 i.e. 10x100 & we can complete the TipAdjust with 0$ also
    }
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response - Upon transaction success or decline
{
    "iposTransactResponse": {
        "responseCode": "iPOS-HP response code like 200, 400",
        "responseMessage": "Successful/Declined",
        "errResponseCode": "Error response code from PG",
        "errResponseMessage": "Error response message from PG",
        "transactionReferenceId": "merchant unique transaction reference id sent on request",
        "transactionType": "7-tipadjust",
        "transactionId": "Unique transaction Id of PG",
        "amount": "amount or total amount refunded",
        "responseApprovalCode": "response approval code from processor ex: TAS164",
        "rrn": "retrieval reference number from processor #219313501821",
        "transactionNumber": "4 digits of transaction invoice number from processor",
        "batchNumber": "3 digits of batch number from processor"
    }
}

iPOSTransact API – (Postman) Simulator URL

URLhttps://documenter.getpostman.com/view/21863361/2s83tCKYRA (opens in a new tab)
ZERO DOLLAR TIP ADJUST
Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": <7-tipadjust>,
        "rrn": "<rrn Number>", // RRN number received for original Transaction
        "amount": "" // TipAdjust , example 1000 for $0 i.e. 10x100
    }
}
Payment Processor Response - Upon transaction success or decline
{
    "iposhpresponse": {
        "responseCode": "response Code 200 Or 400 For Bad Request",
        "responseMessage": "Success Or Failure",
        "transactionReferenceId": "transaction ReferenceId Of Trasanction",
        "transactionType": "7",Transaction Type
        "transactionId": "41896813200027362820250620094822",Transaction Id Of Transaction
        "amount": "0", Amount
        "responseApprovalCode": "613520",
        "rrn": "517109501225"RRN Of The Transaction Original Sale,
        "transactionNumber": "3",
        "batchNumber": "Batch Number Of Transaction",
        "totalAmount": "0"Amount
    }
}

INCREMENTAL AUTH

Request Body
{
    "merchantAuthentication": {
        "merchantId": "962923571839",
        "transactionReferenceId": "87813a46a578216876a3"
    },
    "transactionRequest": {
        "transactionType": 8,
        "amount": "500",
        "rrn": "412308501306"
    },
    "preferences": {
        "eReceipt": true,
        "customerName": "Customer_Name",
        "customerEmail": "Customer_Email",
        "customerMobile": "+919030427945"
    }
}
Response Body
 {
    "iposhpresponse": {
        "responseCode": "200",
        "responseMessage": "Success",
        "errResponseCode": "",
        "errResponseMessage": "",
        "transactionReferenceId": "87813a46a578216876a3",
        "transactionType": "11",
        "transactionId": "64488977724057183920240503023758",
        "amount": "500",
        "responseApprovalCode": "TAS437",
        "rrn": "412308501306",
        "transactionNumber": "19",
        "batchNumber": "318",
        "totalAmount": "500",
        "customFee": "",
        "localTax": "",
        "stateTax": ""
    }
}

OPEN BATCH

Request
{
    "merchantAuthentication": {
        "merchantId": "258823860131"
    },
    "transactionRequest": {
        "transactionType": 9
    }
}
Response Successful
{
    "iposhpresponse": {
        "total_without_fee": 93.31,
        "batch_number": "432",
        "batch_profiles": [
            {
                "withoutLocalTaxAmount": 82.58,
                "without_tax": 75.4,
                "batch_summary": [
                    {
                        "inx": "1",
                        "amount": 96.94,
                        "profileId": "01",
                        "type": "SALE",
                        "txName": "SALE",
                        "transaction_no": 2
                    }
                ],
                "batch_number": "432",
                "fee": 3.63,
                "batch_details": [
                    {
                        "surcharge": 0,
                        "reducedTaxFee": "",
                        "groupType": null,
                        "approvalCode": "TAS996",
                        "externalRefId": "0",
                        "tagValue": null,
                        "discount": 0,
                        "appCode": "TAS996",
                        "type": "SALE",
                        "voidFlag": "N",
                        "posRequestTime": "05:33:38",
                        "invoiceNumber": "000001",
                        "onlyTipAmt": 0,
                        "customFee": 0,
                        "approvedAmount": 20.65,
                        "commercialTaxAmount": 0,
                        "reducedTax": 0,
                        "tagLabel": null,
                        "serviceFee": 0,
                        "amount": 20.65,
                        "tipAmount": 0,
                        "merchantFee": 0,
                        "transactionId": "18019819047186013120240502053338",
                        "stateTaxAmount": 1.59,
                        "baseAmount": 15.88,
                        "rrn": "412305501499",
                        "localTaxAmount": 3.18,
                        "feeAmount": 0,
                        "profileId": "01",
                        "adjustedTipAmount": 0,
                        "totalTaxAmount": 4.77,
                        "posRequestDate": "2024-05-02",
                        "account": "424242******4242",
                        "card": "VISA"
                    }
                ],
                "discount": 0,
                "settleDate": null,
                "batchBase": 71.77,
                "batch_total": 96.94,
                "stateTaxAmount": 7.18,
                "withoutStateTaxAmount": 89.76,
                "localTaxAmount": 14.36,
                "without_discount": 96.94,
                "profile_name": "with fee",
                "without_tip": 96.94,
                "profileCode": "01",
                "tip": 0,
                "without_fee": 93.31,
                "taxAmount": 21.54,
                "transaction_no": 2,
                "processorData": {
                    "Agent": "000000",
                    "Chain": "111111",
                    "TermNo": "1515",
                    "Agent_FIID": "8954",
                    "Mid": "888000003338",
                    "Store": "5999",
                    "dsGroup": "894895618956",
                    "TermId": "75091651",
                    "ABA_No": "894789561"
                }
            }
        ],
        "total_transactions": 2,
        "total_fee": 3.63,
        "cash_payment": {
            "data": [],
            "cash_payment_total": 0,
            "cash_txn_count": 0
        },
        "alter_payments": {
            "alter_txn_count": 27,
            "data": [
                {
                    "approvalCode": "00",
                    "txTime": "12:36:41",
                    "DiscountFee": 0,
                    "createdAt": "2024-05-02T07:06:46.000Z",
                    "posResponseCode": "00",
                    "invoiceNumber": null,
                    "onlyTipAmt": 0,
                    "id": "9fed09f6-4c97-4ce4-8974-2d22c4dea69c",
                    "cashDiscount": 0,
                    "txName": "SALE",
                    "updatedAt": "2024-05-02T07:07:12.000Z",
                    "serviceFee": 0,
                    "hostResponseCode": "00",
                    "maskedPan": "0000000011101010",
                    "additionalDetails": null,
                    "transactionId": "66349652588238601311714633606512",
                    "destType": "ACH",
                    "txAmount": 15.45,
                    "rrn": "204180145",
                    "transactionType": "CHECK",
                    "totalAmount": 15.45,
                    "tpn": "258823860131",
                    "sourceType": "ACH",
                    "commonMode": "WIFI",
                    "txDate": "2024-05-02T08:36:41.000Z"
                }
            ],
            "alter_payment_total": 410.08
        },
        "total_tip": 0,
        "batch_total": 96.94
    }
}
Response Failure
{
    "iposhpresponse": {
        "field": "IPOS_BATCH_001",
        "message": "no open batch for this TPN"
    }
}

BATCH SETTLEMENT

iPOSTransact API – Batch Settlement – JSON Request Sample

Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": 4 // Batch settlement
    }
}

iPOSTransact API – Batch Settlement – JSON Response Sample

iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.transactionType",
            "message": "Invalid Transaction Type"
        },
        ...
    ]
}
Payment Processor Response - Upon batch settlement transaction success or decline response
{
    "iposTransactResponse": {
        "responseCode": "iPOS-HP response code like 200, 400, ...",
        "responseMessage": "Successful/Declined",
        "errResponseCode": "Error response code",
        "errResponseMessage": "Error response message",
        "transactionReferenceId": "merchant unique transaction reference id sent on request",
        "transactionType": 4, // batch settlement
        "transactionId": "Unique transaction Id of payment processor",
        "transactionNumber": "4 digits of transaction number from payment processor",
        "batchNumber": "3 digits of batch number from payment processor",
        "amount": "base amount or total amount charged",
        "responseApprovalCode": "response approval code from processor ex: TAS164",
        "RRN": "retrieval reference number from processor #219313501821"
    }
}

iPOSTransact API – Batch Settlement Transaction (Postman URL)

Version 3 (Use v3 End Points)

ObjectsDescription
Sandbox URL * https://payment.ipospays.tech/api/v3/iposTransact
Production URL * https://payment.ipospays.com/api/v3/iposTransact

Version 2

ObjectsDescription
Sandbox URL * https://payment.ipospays.tech/api/v2/iposTransact
Production URL * https://payment.ipospays.com/api/v2/iposTransact

Version 1

ObjectsDescription
Sandbox URL * https://payment.ipospays.tech/api/v1/iposTransact
Production URL * https://payment.ipospays.com/api/v1/iposTransact

Sample Requests and Responses for ACH

SALE

JSON Request Sample

Post head request(header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "567024937072",// TPN provided by Dejavoo
        "transactionReferenceId": "7639491755250417905532" //Unique TransactionRefId for each Transaction
    },
    "transactionRequest": {
        "transactionType": 10,//ACH - Sale transaction 
        "amount": "",// Example: 1000 = $10.00 (amount is in cents, divided by 100)
        "achProcessor" : 1,//PAYA-1        //Processor Value whether its PAYA or others 
"achToken":"05944FB3E1DA4663868455AF630F45BE"// Token received in webhooks or returnURL
    },
    "preferences": {
        "eReceipt": true,
        "customerEmail": "Customer_Email",// Customer Email Id
        "customerMobile": "+1234567891", // Customer Mobile Number
        "requestAchToken": true // true- Then it will share the achToken in Response if transaction is Approved. False - We will not share the achToken
    }
}
Transact API - JSON Response Sample
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response
{
    "iposhpresponse": {
        "hostResponseCode": "00",
        "message": "Approved",
	    "paymentMethod":"SALE",
        "transactionType": 10,
	    "amount":"10"
        "achToken": "05944FB3E1DA4663868455AF630F45BE",
        "transactionId": "35999115670249370721746687387468",
        "rrn": "BT_-868Igb-q5sZ_AW34BvvAcmy6f-aadqAN"
    }
}

VOID

JSON Request Sample

Post head request(header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "567024937072",
        "transactionReferenceId": "763949175532505796532"
    },
    "transactionRequest": {
        "transactionType": 11, // Void need to pass as 11
        "amount": "", // Example: 1000 = $10.00 (amount is in cents, divided by 100)
        "achTransactionId":"64679415670249370721746685143724"// Need to provide the transactionId provided in ACH Sale Response
    },
    "preferences": {
        "eReceipt": true,
        "customerEmail": "Customer_Email",// Customer Email Id
        "customerMobile": "+1234567891" //Customer Mobile Number
    }
}

Transact API -JSON Response Sample

iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        }, ...
    ]
}
Payment Processor Response
{
	"iposhpresponse": {
    	"hostResponseCode": "00",
    	"message": "Approved",
    	"paymentMethod": "VOID SALE",
    	"transactionType": 11,
    	"amount": "1000",
    	"transactionId": "46882215670249370721746700140534",
    	"rrn": "z-H0Wd0kWgzRHov6wjTVpFVHEmaB6SXiyVoK"
	}
}

REFUND

JSON Request Sample

Post head request(header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "567024937072",
        "transactionReferenceId": "763949175532505796532"
    },
    "transactionRequest": {
        "transactionType": 11, // Refund need to pass as 11
        "amount": "", // Example: 1000 = $10.00 (amount is in cents, divided by 100)
        "achTransactionId":"64679415670249370721746685143724"// Need to provide the transactionId provided in ACH Sale Response
    },
    "preferences": {
        "eReceipt": true,
        "customerEmail": "Customer_Email",// Customer Email Id
        "customerMobile": "+1234567891" //Customer Mobile Number
    }
}

Transact API -JSON Response Sample

iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        }, ...
    ]
}
Payment Processor Response
{
	"iposhpresponse": {
    	"hostResponseCode": "00",
    	"message": "Approved",
    	"paymentMethod": "REFUND SALE",
    	"transactionType": 11,
    	"amount": "1000",
    	"transactionId": "46882215670249370721746700140534",
    	"rrn": "z-H0Wd0kWgzRHov6wjTVpFVHEmaB6SXiyVoK"
	}
}

SALE with ACH Data from Freedom to Design

Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "567024937072",// TPN provided by Dejavoo
        "transactionReferenceId": "7639491755250417905532" //Unique TransactionRefId for each Transaction
    },
    "transactionRequest": {
        "transactionType": 10,//ACH - Sale transaction 
        "amount": "1000",// Example: 1000 = $10.00 (amount is in cents, divided by 100)
        "achProcessor" : 1,//PAYA-1        //Processor Value whether its PAYA or others
    },
    "preferences": {
        "eReceipt": true,
        "customerEmail": "Customer_Email",// Customer Email Id
        "customerMobile": "+1234567891", // Customer Mobile Number
        "requestAchToken": true // true- Then it will share the achToken in Response if transaction is Approved. False - We will not share the achToken
    },
	"achData": {
    "firstName": "fdhg",
    "lastName": "ghfg",
    "addressOne": "hggfhg",
    "state": "AP",
    "dlNumber": "456546545757",
    "dlState": "BC",
    "accountNumber": "35465754767",
    "accountType": "Savings",
    "routingNumber": "546565777",
    "ssn": "5467",
    "dobYear": "2000",
    "city": "ghfghgj",
    "zipCode": "54667",
    "identity": true,
    "terminalId": "2313",
    "entryClass": "WEB",
    "usersId": "fFLRZYRbeQMbmPBRy0dPl",
    "tipAmount": "0"
  }
}
Transact API - JSON Response Sample
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}

Transaction Status Check API

The Transaction Status Check API allows you to check the current status of a payment transaction.

This is useful for confirming whether a transaction was:

  • Successful

  • Failed

  • Pending

  • Cancelled

  • Or in any other custom-defined state.

This API works for both standard card transactions and alternate payment types like wallets or ACH.

Use the following format to request the status of a card-based transaction:

Transaction Status Check API – Request (Standard)
{
  "merchantAuthentication": {
    "merchantId": "962923571839",                 // This is the TPN (Terminal Profile Number)
    "transactionReferenceId": "3245623463254631"  // This is the unique reference ID of the transaction
  }
}

Here’s a sample response for a successful Sale transaction:

Transaction Status Check API – Response (Standard)
{
  "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"
    }
  }
}

Alternate Payment (ACH) – Transaction Status Check API

For payments made via wallets, ACH, or other alternate methods, use this version of the API.

Alternate Payment – Request
{
  "merchantAuthentication": {
    "merchantId": "962923571839",
    "transactionReferenceId": "transactionReferenceId or rrn or transactionId"
  }
}
Alternate Payment – Response
{
  "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"
    },
    "TxDetail": {
      "DateNTime": "11750855554528",
      "Tpn": "567025324141"
    }
  }
}

Transaction Status Check – Error Response Example

Request with Invalid Transaction Reference ID
{
  "merchantAuthentication": {
    "merchantId": "962923571839",
    "transactionReferenceId": "3245623463254631S2343W12345354356"  // Invalid ID
  }
}
Error Response
{
  "errors": [
    {
      "field": "IPOSTRANCT_001",
      "message": "No Transaction Registered with This TransactionRefId. Please try with valid details.",
      "bulbIconRequired": false
    }
  ]
}

HSA/FSA Card Acceptance

To accept Health Savings Account (HSA) and Flexible Spending Account (FSA) cards, send the request shown below through the iPOS Transact API.

Request Format with Medical Line Items
{
  "merchantAuthentication": {
    "merchantId": "254525842756",
    "transactionReferenceId": "4324244324e56534"
  },
  "transactionRequest": {
    "transactionType": 10000,
    "amount": "100",
    "cardToken": "D20F10025CFC287AB694BE8732BE24ECC8660DF0D1DAB462",
    "rrn": "513413754251",
    "applySteamSettingTipFeeTax": true
  },
  "preferences": {
    "eReceipt": true,
    "customerName": "AK",
    "customerEmail": "denovo123@gmail.com",
    "customerMobile": "+919898989898",
    "requestCardToken": false,
    "integrationVersion": "v2"
  },
  "hsa": {
    "HSA_TotalAmount": "900",
    "HSA_RxAmount": "100",
    "HSA_DentalAmount": "200",
    "HSA_ClinicAmount": "300"
  }
}
Request Format with Vision/Optical Amount
{
  "merchantAuthentication": {
    "merchantId": "254525842756",
    "transactionReferenceId": "4324244324e56534"
  },
  "transactionRequest": {
    "transactionType": 10000,
    "amount": "100",
    "cardToken": "D20F10025CFC287AB694BE8732BE24ECC8660DF0D1DAB462",
    "rrn": "513413754251",
    "applySteamSettingTipFeeTax": true
  },
  "preferences": {
    "eReceipt": true,
    "customerName": "AK",
    "customerEmail": "denovo123@gmail.com",
    "customerMobile": "+919898989898",
    "requestCardToken": false,
    "integrationVersion": "v2"
  },
  "hsa": {
    "HSA_VisionAmount": "2000"
  }
}
Response Example
{
  "iposhpresponse": {
    "responseCode": "200",
    "responseMessage": "Success",
    "transactionReferenceId": "4344434efef46341",
    "transactionType": "1",
    "transactionId": "58446072246384275620250530055715",
    "amount": "300",
    "responseApprovalCode": "VTLMC1",
    "rrn": "515005503037",
    "transactionNumber": "39",
    "batchNumber": "570",
    "totalAmount": "312",
    "customFee": "12",
    "HSA": "Y"
  }
}

Error Response Code & Messages

For a complete list of error codes and their explanations, please visit our Error Codes Reference Page.

Error Codes & Messages
iPOS TransactOnboard Merchant