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
05/08/25 Introduced support for Encrypted Card Data and added Authentication Token API, enabling users to securely generate tokens via API instead of the portal.Use the V3 endpoint to send encrypted card data, perform transactions such as Sale, Refund, Void, and more, and generate/manage authentication tokens via the Authentication Token API instead of manual portal-based token generation.
25/09/25 Added Gift transactioniPOS Transact V1 and above
19/10/25 Added Level 3 / VISA CEDP support for transactionsiPOS Transact V1

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 TPN.

  • For Production (Live)

Users should be onboarded on 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

How to Generate an Authentication Token

If you are using Version 1 or Version 2 of the iPOS Transact API, follow these steps to generate an authentication token:

Step 1 : Log in to your merchant account on the iPOSpays portal and navigate to the Settings section.

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

  • Select your TPN from the dropdown menu.

  • Click the Generate Token button to create a new authentication token.

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

If you’re using Version 3 of the iPOS Transact API, authentication is handled through a dedicated token generation API. Follow the steps below to obtain your token:

Step 1: Access the Authentication Token API

Refer to the official documentation to understand the request structure and response handling:

iPOSpays Authentication Token API

Step 2: Prepare Your API Credentials

Before making a request, ensure you have the required credentials issued by iPOSpays. These credentials include:

{
  "apiKey": "your_api_key_here",           // Required: Your assigned API key from iPOSpays
  "secretKey": "your_secret_key_here",     // Required: Your assigned secret key from iPOSpays
  "scope": "PaymentTokenization"           // Required: Use "PaymentTokenization" for iPOS Transact API
}

  • apiKey: Provided by iPOSpays. Contact support@dejavoo.io or your Dejavoo representative if you haven’t received it.

  • secretKey: Provided with the API key

  • scope: Must be set to "PaymentTokenization" for iPOS Transact usage

For the iPOS Transact V3 endpoint, all three fields (apiKey, secretKey, and scope) are required. For other endpoints, including all these fields may not be mandatory.

Step 3: Use the Token

Once the API call is successful, a valid authentication token will be returned in the response.

Include this token in the header of your subsequent iPOS Transact API requests.

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.

  • Gift - A Gift Transaction refers to a transaction where a customer uses a gift card balance as a payment method to complete a purchase.

  • Level 3 / VISA CEDP (Sale): - A Level 3 / VISA CEDP sale transaction enables you to include detailed line-item information in the sale requests. By providing this enhanced transaction data, you can qualify for better interchange rates offered by the card networks.

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

For Level 3 / VISA CEDP Transactions

As part of VISA’s updated CEDP (Commercial Enhanced Data Program), Level 3 data is now required for commercial and corporate card transactions to qualify for optimized interchange rates.

To support this, please ensure you are submitting accurate, complete, and properly formatted Level 3 data in your requests. Poor data quality (e.g., missing fields, incorrect values, or placeholder data) may lead to downgraded interchange qualification or rejections.

This includes fields such as item descriptions, quantities, unit costs, tax amounts, and other line-item details. The cleaner and more complete the data, the better the chances of qualifying for enhanced rates.

Sale Transaction

A Level 3 / VISA CEDP sale transaction enables you to include detailed line-item information in the sale requests. By providing this enhanced transaction data, you can qualify for better interchange rates offered by the card networks.

You can send Level 3 / VISA CEDP line items in a sale transaction using cardToken and paymentTokenId. Sample request for both methods are provided below.

Jump toSample Sale Request Using cardToken
Jump toSample Sale Request Using paymentToken

End Points and Objects

Request Method

HTTPS Request MethodPOST

End Points

All three versions of the iPOS Transact API— V1, V2, and V3—support the full range of transaction types, including Sale, Refund, Pre-Auth, Void, Tip Adjust, and more.

However, the differences between them lie in feature enhancements and security capabilities, which evolved across versions.

VersionDescriptionSandbox EndpointProduction Endpoint
V3Latest version. Supports all transactions, AVS, encrypted card data, and API-based token generationhttps://payment.ipospays.tech/api/v3/iposTransact (opens in a new tab)https://payment.ipospays.com/api/v3/iposTransact (opens in a new tab)
V2All transactions and AVS support. Requires portal-based token generationhttps://payment.ipospays.tech/api/v2/iposTransact (opens in a new tab)https://payment.ipospays.com/api/v2/iposTransact (opens in a new tab)
V1All transactions and AVS support. Requires portal-based token generationhttps://payment.ipospays.tech/api/v1/iposTransact (opens in a new tab)https://payment.ipospays.com/api/v1/iposTransact (opens in a new tab)

Always use the appropriate version based on your transaction and data security requirements.

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)

12 - Gift

cardToken* * String Required

Tokenized card value used to capture the specified amount.

Reusable for multiple transactions.

Format: Encrypted token string.

paymentTokenId String Conditional

Tokenized payment value used to capture the specified amount for a single-use transaction (applicable only for Sale transactions via Freedom to Design).

Cannot be used as cardToken.

Format: Encrypted token string.

applySteamSettingTipFeeTax * String Required

Determines whether tips, fees, and taxes are automatically calculated using the settings in S.T.E.A.M → Edit Parameter on the portal and added to the base amount.

Values: true, false

Default: false

If true:

The iposTransact API calculates tips, fees, taxes, and Level 3 line-item fees based on S.T.E.A.M parameters and adds them to the base amount.

If false:

The amount in the request payload is treated as the final total.

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 - Works on V1,2 & 3 )
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.

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.

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.

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.

Level 3 / VISA CEDP Payload Specification

Object – Conditional field containing Level 3 transaction details.

Variable NameDescription
HeaderThis data contains the L3 Header information required to process the transaction at Level 3. Type: Object
ItemsThis data contains product information that needs to be processed at Level 3. Type: Object
FieldTypeUsage ConditionDescription
Headers ( Obj – Conditional (Level 3 Information) )
TaxAmount * double Mandatory

This is a CEDP summary header field that specifies the monetary amount of any additional sales tax applied to the transaction. Send 0 if no additional tax applies.

Value: 1.05

Length: 12

LocalTaxFlag * Integer Mandatory

This is a CEDP summary header field that indicates the type of local tax applied.

Valid Values: 0 = Not provided, 1 = Local/sales tax, 2 = Tax-exempt.

Value: 0,1,2

Length: 1

NationalTaxAmount double Optional

This is a CEDP summary header field that specifies the total national or federal tax included in the transaction. Send 0 if no national tax applies.

Value: 1.25

Length: 12

DestZipCode String Conditional

This is a CEDP summary header field that specifies the postal or ZIP code of the destination address for shipped goods (up to 12 characters). Provide the actual shipping ZIP/postal code to qualify for line-item reporting benefits.

Value: 45451

Length: 12

SummaryCommodityCode String Optional

This is a CEDP summary header field that specifies an international commodity code representing the goods or services supplied. 4-character alphanumeric. Provide the correct code to maximize interchange.

Value: 2123

Length: 4

TaxRateApplied double Conditional

This is a CEDP summary header field that specifies the rate used to calculate tax for the transaction. 4-character numeric with implied two-digit decimal. Send 0 if no tax applies.

Value: 15

Length: 2

TotalDiscountAmount double Conditional

This is a CEDP summary header field that contains the total discount amount applied against the line item total. Send 0 if no discount applies.

Value: 10.25

Length: 12

PoNumber String Optional

This is a CEDP summary header field that contains a Purchase Order Number provided by the Visa or Mastercard Purchasing Card cardholder. Alphanumeric, 16, 17, or 25 characters. Include if available.

Value: 10123456

Length: 25 (Max)

FreightAmount double Conditional

This is a CEDP summary header field that specifies the freight or shipping portion of the total transaction amount. Send 0 if not applicable.

Value: 1.25

Length: 12

DutyAmount double Conditional

This is a CEDP summary header field that specifies the fee amount associated with the import of purchased goods.

Value: 1.26

Length: 12

ShipFromZipCode String Conditional

This is a CEDP summary header field that specifies the postal or ZIP code of the address from which purchased goods are shipped (up to 10 characters). Provide actual shipping origin ZIP/postal code to qualify for line-item reporting benefits.

Value: 0000011111

Length: 10 (Max)

DestCountryCode String Conditional

This is a CEDP summary header field that contains the three-character code of the country where the goods are being shipped. Provide the actual country code.

Value: 840

Length: 3

MerchantTaxId String Optional

This is a CEDP summary header field that contains the government-assigned tax identification number of the merchant. Provide the merchant tax ID if applicable; leave blank if not.

Value: 99999999999999999999

Length: 15

LineItemCount * String Mandatory

This is a CEDP summary header field that contains the total number of line item detail records associated with the transaction.

Valid Values: Visa: 000–998, Mastercard: 000–098.

Value: 001 (Default)

Length: 3

AltTaxAmount double Optional

This is a CEDP summary header field that records the second tax amount in countries where more than one type of tax may apply. Send 0 if not applicable.

Value: 1.26

Length: 12

PurchaseIdentifier String Conditional

This is a CEDP summary header field that contains a 25-character identifier assigned by the merchant. Provide if available; value must not be all zeroes or spaces. Leave blank if not used.

Value: 452546456464646497854645

Length: 25

PurchaseIdFormatCode * Char Mandatory

This is a CEDP summary header field that contains a one-character code identifying the type of Purchase Identifier associated with the transaction.

Valid Values: Z = Not Used, 0 = Reserved, 1 = Direct Marketing Order Number, 2 = Reserved, 3 = Auto Rental Agreement Number.

Value: Z,0,1,2,3

Length: 1

OrderDate String Conditional

This is a CEDP summary header field that contains the purchase order date in YYMMDD format. Provide the actual order date if available.

Value: 251016

Length: 6

AltTaxIndicator String Optional

This is a CEDP summary header field that indicates whether the Alternate Tax Amount is included in the purchase amount: 1 = Included, 0 = Not included.

Valid Values: 1,0

Value: 1,0

Length: 1

L3 Group Fields – Line Item Details ( Each group represents a single line item in the transaction, providing item-level details required for Level 3 (CEDP) processing. )
CommodityCode String Conditional

This is a CEDP line item group field that contains an international or national standardized code for the individual good or service being supplied. Provide the correct commodity code for the item to maximize interchange benefits.

Value: –

Length: 12

Description * String Mandatory

This is a CEDP line item group field that contains a description of the item(s) being supplied. 35-character alphanumeric field, left-justified and space-filled. Provide a clear description.

Value: –

Length: 35

ProductCode String Optional

This is a CEDP line item group field that contains a merchant-defined description code for the item being purchased. 4-character field, left-justified and space-filled. Provide if available.

Value: –

Length: 4

Quantity * double Mandatory

This is a CEDP line item group field that contains the quantity of the item(s) being purchased. 12-character numeric field, right-justified and zero-filled. Send the actual quantity.

Value: 1

Length: 12

UnitOfMeasure * String Mandatory

This is a CEDP line item group field that contains the code for the unit of measurement used in international trade (e.g., EA, KG). 12-character alphanumeric, left-justified and space-filled.

Value: KG

Length: 12

UnitCost * double Mandatory

This is a CEDP line item group field that contains the unit cost of the item. 12-character numeric field with an implied 4-digit decimal, right-justified and zero-filled. Provide actual unit cost.

Value: 12.44

Length: 4

TaxAmount double Conditional

This is a CEDP line item group field that contains the amount of any value-added or alternate tax associated with the purchased item. 12-character numeric, right-justified and zero-filled. For US merchants, send 0 unless another applicable tax applies.

Value: 204.33

Length: 12

TaxRate * double Mandatory

This is a CEDP line item group field that contains the tax rate used to calculate the TaxAmount. 4-character numeric field with a two-character implied decimal, right-justified and zero-filled. For US merchants, send 0 unless another tax applies.

Value: 2343

Length: 4

DiscountAmount * double Mandatory

This is a CEDP line item group field that contains any discount applied to the line item. 12-character numeric field, right-justified and zero-filled. Provide actual discount amount; send 0 if none.

Value: 21.54

Length: 12

DiscountRate double Conditional

This is a CEDP line item group field that contains the discount rate applicable to the line item if DiscountIndicator = Y. 9-character numeric field. Provide the discount rate; otherwise, send 0.

Value: 12.63

Length: 9

DiscountIndicator * Integer Mandatory

This is a CEDP line item group field indicating whether a discount was applied: Y = discounted, N = not discounted, blank = not supported. 1-character field.

Valid Values: Y = 1, N = 0

Value: Y(1), N(0)

Length: 1

NetGrossIndicator String Optional

This is a CEDP line item group field indicating whether the item amount includes tax: N = does not include tax, Y = includes tax. 1-character field. For US merchants, N is typically used.

Valid Values: N, Y

Value: N, Y

Length: 1

DebitCreditIndicator String Optional

This is a CEDP line item group field indicating whether the line item amount is a Credit (C) or Debit (D). 1-character field.

Valid Values: C, D

Value: C, D

Length: 1

ExtLineAmount double Optional

This is a CEDP line item group field containing the total amount of the individual item (price × quantity). 9-character numeric field, right-justified and zero-filled. Provide actual total amount.

Value: 23.12

Length: 4

AltTaxID Integer Optional

This is a CEDP line item group field containing the tax ID of the merchant reporting alternate tax. 4-character numeric field. Send if alternate tax applies; otherwise leave blank.

Value: 3223

Length: 4

TaxTypeApplied String Optional

This is a CEDP line item group field defining a tax category that may apply to domestic processing arrangements. 4-character alphanumeric field. Provide correct tax type if applicable; otherwise leave blank.

Valid Values: 1,2,3,4

Value: 1,2,3,4

Length: 1

NationalTaxAmount double Optional

This is a CEDP line item group field containing the amount of national tax included in LineItemTotal. Send 0 for US merchants.

Value: 10.25

Length: 12

NationalTaxRate double Optional

This is a CEDP line item group field that contains the national tax rate applicable to the line item. Send 0 for US merchants.

Value: 10.53

Length: 12

TaxIndicator Integer Conditional

This is a CEDP line item group field indicating the type or characteristic of the tax applied. 1-character field. Send 1 if tax applies, 2 if transaction is tax-exempt, 0 if tax is not provided.

Valid Values: 0,1,2

Value: 0,1,2

Length: 1

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

23 - Gift

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

giftBalAmount string Required

Remaining gift card balance after the transaction (same units).

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

HSA String Optional

Response as “Y” means this transaction is processed as HSA.

If it is not processed as HSA then we will not send this field as response data.

l2l3ValidationError String Conditional

This field indicates whether any mandatory Level-3 tag is missing. If a required tag is not provided, the transaction will not be processed. The Level-3 transaction response will include details specifying which field caused the failure.

l2l3Flag String Conditional

This field indicates whether the transaction is processed with Level-3 data.

Valid Values:

“Y” = Processed as Level-3

“N” = Not processed as Level-3

“E” = Not processed as Level-3 due to an error or missing

mandatory Level-3 tags.

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",
        "requestCardToken": false
    },
    "Avs": {
        "StreetNo": "23453",
        "Zip": "12344"
    }
}

HSA Object

This object is required only when processing HSA card transactions:
{
  "hsa": {
    "totalAmount": "1400",
    "prescriptionAmount": "500",
    "dentalAmount": "200",
    "clinicAmount": "300"
  },
 
  (or)
 
  "hsa": {
    "opticalAmount": "1200"
  }
}

L3Data Object

This object contains Level 3 (CEDP) transaction data, including header-level summary information and line-item details. It is used when submitting Level 3 data for enhanced transaction processing, which may improve interchange rates. The object is required when Level 3 data is available, not limited to any specific card type.

{
  "L3Data": {
    "Header": {
      "TaxAmount": 1.23,
      "LocalTaxFlag": 1,
      "NationalTaxAmount": 2.23,
      "DestZipCode": "23432",
      "SummaryCommodityCode": "",
      "TaxRateApplied": 6,
      "TotalDiscountAmount": 1.25,
      "PoNumber": "10123456",
      "FreightAmount": 10,
      "DutyAmount": 12,
      "ShipFromZipCode": "23234",
      "DestCountryCode": "840",
      "MerchantTaxId": "457896",
      "LineItemCount": 1,
      "AltTaxAmount": 1,
      "PurchaseIdentifier": "",
      "PurchaseIdFormatCode": "1",
      "OrderDate": "2025-10-16",
      "AltTaxIndicator": true
    },
    "items": [
      {
        "CommodityCode": "12345678901234",
        "Description": "Milk is a diary product",
        "ProductCode": "1234567890",
        "Quantity": 1,
        "UnitOfMeasure": "123456789ITM123",
        "UnitCost": 1,
        "TaxAmount": 3,
        "TaxRate": "",
        "DiscountAmount": 1,
        "DiscountRate": 23443678099,
        "DiscountIndicator": true,
        "NetGrossIndicator": false,
        "DebitCreditIndicator": "",
        "ExtLineAmount": "123456",
        "AltTaxID": 101,
        "TaxTypeApplied": "ccc123",
        "NationalTaxAmount": 2.25,
        "NationalTaxRate": 3.0,
        "TaxIndicator": 3
      }
    ]
  }
}
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",
        "requestCardToken": false
    },
    "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"
    }
}
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",
        "requestCardToken": false
    },
    "Avs": {
        "StreetNo": "23453",
        "Zip": "12344"
    }
},
 
// This HSA object need to defined for only HSA Cards to process the request to HSA
"hsa": {
    "totalAmount": "1400",
    "prescriptionAmount": "500",
    "dentalAmount": "200",
    "clinicAmount": "300"
}
 
(or)
 
"hsa": {
    "opticalAmount": "1200"
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        // Additional errors may be listed here
    ]
}
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",
        "HSA" : "Y" //This field will be sent only when transaction is done with HSA Card and gets approval from switch
    }
}

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"
    }
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        // Additional errors may be listed here
    ]
}
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"
    }
}
 
        "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"
    }
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        // Additional errors may be listed here
    ]
}
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"
        },
        // Additional errors may be listed here
    ]
}
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": "" // Amount to be refunded | TipAdjust | Ticket, example 1000 for $10 i.e. 10x100
          // TipAdjust : You can able to complete the TipAdjust with 0$ (New Enhancement in IposTransact)
    }
}
iPOSTransact API request validation response
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        // Additional errors may be listed here
    ]
}
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"
        },
        // Additional errors may be listed here
    ]
}
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"
        },
        // Additional errors may be listed here
    ]
}
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"
        },
        // Additional errors may be listed here
    ]
}
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"
        },
        // Additional errors may be listed here
    ]
}
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

GIFT

A Gift transaction refers to a transaction where a customer uses a gift card balance as a payment method to complete a purchase.

Sample Request
{
  "merchantAuthentication": {
    "merchantId": "254525842756",                // Unique ID assigned to the merchant
    "transactionReferenceId": "4324244324e56534"
  },
  "transactionRequest": {
    "transactionType": 12,                       // Transaction type code for Gift Transaction
    "amount": "1000",
    "cardToken": "84C80CF2E93DBA227871DF03EAEA4AFD30AAAB26E90368B2" // Tokenized representation of the gift card
  },
  "preferences": {
    "eReceipt": true,
    "customerName": "John",
    "customerEmail": "example@gmail.com",
    "customerMobile": "+919898989898",
    "requestCardToken": false
  }
}
Sample Response
{
  "iposhpresponse": {
    "responseCode": "200",
    "responseMessage": "Success",
    "transactionReferenceId": "4324244324e56534",
    "transactionType": "23",                     // Transaction type identifier for gift redemption
    "transactionId": "15382218148884275620250825062119",
    "amount": "1000",                            // Amount charged to the gift card
    "rrn": "000001692027",
    "transactionNumber": "7",
    "batchNumber": "610",
    "totalAmount": "1000",
    "giftBalAmount": "40187"                     // Remaining balance on the gift card
  }
}

Sample Requests for Level 3 / VISA CEDP

Sample Sale Request Using cardToken

{
  "merchantAuthentication": {
    "merchantId": "962923571839",
    "transactionReferenceId": "7687678687457er3444d4r4e3983"
  },
  "transactionRequest": {
    "transactionType": 1,
    "amount": "233",
    "cardToken": "4FDE6038029EAD4445C8C3396E511B7628A71B677407F8D5",
    "applySteamSettingTipFeeTax": true
  },
  "preferences": {
    "eReceipt": true,
    "customerName": "Shankar",
    "customerEmail": "sthanigaivel@denovsystem.com",
    "customerMobile": "+918072892144"
  },
  "L3Data": {
    "Header": {
      "TaxAmount": 1.23,
      "LocalTaxFlag": 1,
      "NationalTaxAmount": 2.23,
      "DestZipCode": "23432",
      "SummaryCommodityCode": "",
      "TaxRateApplied": 6,
      "TotalDiscountAmount": 1.25,
      "PoNumber": "10123456",
      "FreightAmount": 10,
      "DutyAmount": 12,
      "ShipFromZipCode": "23234",
      "DestCountryCode": "840",
      "MerchantTaxId": "457896",
      "LineItemCount": 1,
      "AltTaxAmount": 1,
      "PurchaseIdentifier": "",
      "PurchaseIdFormatCode": "1",
      "OrderDate": "2025-10-16",
      "AltTaxIndicator": true
    },
    "items": [
      {
        "CommodityCode": "12345678901234",
        "Description": "Milk is a diary product",
        "ProductCode": "1234567890",
        "Quantity": 1,
        "UnitOfMeasure": "123456789ITM123",
        "UnitCost": 1,
        "TaxAmount": 3,
        "TaxRate": "",
        "DiscountAmount": 1,
        "DiscountRate": 23443678099,
        "DiscountIndicator": true,
        "NetGrossIndicator": false,
        "DebitCreditIndicator": "",
        "ExtLineAmount": "123456",
        "AltTaxID": 101,
        "TaxTypeApplied": "ccc123",
        "NationalTaxAmount": 2.25,
        "NationalTaxRate": 3.0,
        "TaxIndicator": 3
      }
    ]
  }
}

Sample Sale Request Using paymentToken

{
  "merchantAuthentication": {
    "merchantId": "962923571839",
    "transactionReferenceId": "7687678687457er3444d4r4e3983"
  },
  "transactionRequest": {
    "transactionType": 1,
    "amount": "233",
    "paymentTokenId": "", // Transactions initiated from Freedom to Design (Optional for GooglePay)
    "applySteamSettingTipFeeTax": true
  },
  "preferences": {
    "eReceipt": true,
    "customerName": "Shankar",
    "customerEmail": "sthanigaivel@denovsystem.com",
    "customerMobile": "+918072892144"
  },
  "L3Data": {
    "Header": {
      "TaxAmount": 1.23,
      "LocalTaxFlag": 1,
      "NationalTaxAmount": 2.23,
      "DestZipCode": "23432",
      "SummaryCommodityCode": "",
      "TaxRateApplied": 6,
      "TotalDiscountAmount": 1.25,
      "PoNumber": "10123456",
      "FreightAmount": 10,
      "DutyAmount": 12,
      "ShipFromZipCode": "23234",
      "DestCountryCode": "840",
      "MerchantTaxId": "457896",
      "LineItemCount": 1,
      "AltTaxAmount": 1,
      "PurchaseIdentifier": "",
      "PurchaseIdFormatCode": "1",
      "OrderDate": "2025-10-16",
      "AltTaxIndicator": true
    },
    "items": [
      {
        "CommodityCode": "12345678901234",
        "Description": "Milk is a diary product",
        "ProductCode": "1234567890",
        "Quantity": 1,
        "UnitOfMeasure": "123456789ITM123",
        "UnitCost": 1,
        "TaxAmount": 3,
        "TaxRate": "",
        "DiscountAmount": 1,
        "DiscountRate": 23443678099,
        "DiscountIndicator": true,
        "NetGrossIndicator": false,
        "DebitCreditIndicator": "",
        "ExtLineAmount": "123456",
        "AltTaxID": 101,
        "TaxTypeApplied": "ccc123",
        "NationalTaxAmount": 2.25,
        "NationalTaxRate": 3.0,
        "TaxIndicator": 3
      }
    ]
  }
}

Sample Response for VISA/CEDP with Sale Transaction

{
    "iposhpresponse": {
        "consumerId": "55TSKB6V3WUG",
        "responseCode": "400",
        "responseMessage": "Failed",
        "errResponseCode": "05",
        "errResponseMessage": "PLS TRY FULL PAN",
        "transactionReferenceId": "7687678687457er3444d4r4e39851",
        "transactionType": "1",
        "transactionId": "40690497613257183920251126072756",
        "amount": "233",
        "totalAmount": "403",
        "customFee": "100",
        "localTax": "47",
        "stateTax": "23",
        "l2l3ValidationError": null,
        "l2l3Flag": "N"
    }
}

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"
        },
        // Additional errors may be listed here
    ]
}
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"
        }, 
        // Additional errors may be listed here
    ]
}
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"
        },
        // Additional errors may be listed here
    ]
}
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": "567025324141",// TPN provided by Dejavoo
    "transactionReferenceId": "TPN258824586753UID14474910"// Unique TransactionRefId for each Transaction
  },
  "transactionRequest": {
    "transactionType": 10,// ACH - Sale transaction
    "amount": 100,// Example: 1000 = $10.00 (amount is in cents, divided by 100)
    "sourceType": "ACH-FTD"//Source Type as ACH-FTD
  },
  "preferences": {
    "customerName": "Test Test",
    "customerEmail": "ashok@gmail.com",// Customer Email Id
    "customerMobile": "+19898989898", // 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": "Test",
    "lastName": "Test",
    "addressOne": "123 ABC RD",
    "addressTwo": "123 ABC RD",
    "state": "FL",
    "dlNumber": "jhkhj8798797",
    "dlState": "FL",
    "accountNumber": "45368648658",
    "accountType": "Savings",// Or Checking
    "routingNumber": "490000018",
    "ssn": "",
    "dobYear": "1999",
    "city": "Mobile",
    "zipCode": "40299",
    "identity": true,
    "terminalId": "2313",
    "entryClass": "WEB",
    "usersId": "50N6Jd0Ng5bnIV1BTs1zZ",
    "tipAmount": "0",
    "tagLabel": "",
    "tagValue": "",
    "custom1": "",
    "custom2": "",
    "custom3": ""
  }
}
Transact API - JSON Response Sample
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        // Additional errors may be listed here
    ]
}

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 TransactClear Card Encryption