iPOS Transact API
Version History
Date | Details | End Points |
---|---|---|
30/09/22 | Initial release | iPOS Transact V1 and above |
30/05/24 | Version 2 - AVS Obj | iPOS Transact V2 and above |
20/08/24 | Ticket, Tip Adjust - transaction type | iPOS Transact V2 and above |
28/01/25 | Google pay | iPOS Transact V2 and above |
29/04/25 | Paya Token | iPOS Transact V2 and above |
08/05/25 | ACH Token | iPOS Transact V2 and above |
13/05/25 | HSA card Features | iPOS Transact V2 and above |
21/05/25 | Version 3 - Encrypted Card Data | iPOS 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:
"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.
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.
End Points and Objects
Request Method
HTTPS Request Method | POST |
---|
End Points
Version 3 (Use v3 End Points)
Objects | Description |
---|---|
Sandbox URL * | https://payment.ipospays.tech/api/v3/iposTransact |
Production URL * | https://payment.ipospays.com/api/v3/iposTransact |
Version 2
Objects | Description |
---|---|
Sandbox URL * | https://payment.ipospays.tech/api/v2/iposTransact |
Production URL * | https://payment.ipospays.com/api/v2/iposTransact |
Version 1
Objects | Description |
---|---|
Sandbox URL * | https://payment.ipospays.tech/api/v1/iposTransact |
Production URL * | https://payment.ipospays.com/api/v1/iposTransact |
Request Parameters - Header Objects
Objects | Description |
---|---|
token | AuthToken (can be obtained from portal settings). |
JSON Content-Type | application/json |
Request Parameters - Body Objects
Objects | Usage Condition | Description |
---|---|---|
merchantAuthentication | Required | Includes merchant authentication details, such as the TPN number and unique transaction reference ID. |
transactRequest | Required | Contains details such as transaction type, card token, amount, fee calculation, etc. |
preferences | Required | Specifies whether AVS (Address Verification Service) verification is needed or if an e-receipt should be sent via SMS/email to the end user. |
AVS | Required | Provides AVS details, including street number and ZIP code. |
Field | Type | Usage Condition | Description | |
---|---|---|---|---|
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> | |
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
Field | Type | Usage Condition | Description | |
---|---|---|---|---|
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)
{
"token": ""
};
{
"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
}
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
},
...
]
}
{
"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)
{
"token": ""
};
{
"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
}
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
},
...
]
}
{
"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)
{
"token": ""
};
{
"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"
}
}
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
},
...
]
}
{
"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)
Objects | Description |
---|---|
Sandbox URL * | https://payment.ipospays.tech/api/v3/iposTransact |
Production URL * | https://payment.ipospays.com/api/v3/iposTransact |
Version 2
Objects | Description |
---|---|
Sandbox URL * | https://payment.ipospays.tech/api/v2/iposTransact |
Production URL * | https://payment.ipospays.com/api/v2/iposTransact |
Version 1
Objects | Description |
---|---|
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)
{
"token": ""
};
{
"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>"
}
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
},
...
]
}
{
"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)
{
"token": ""
};
{
"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>"
}
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
},
...
]
}
{
"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)
{
"token": ""
};
{
"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"
}
}
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
},
...
]
}
{
"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)
URL | https://documenter.getpostman.com/view/21863361/2s83tCKYRA (opens in a new tab) |
---|
VOID
{
"token": ""
};
{
"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)
}
}
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
},
...
]
}
{
"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
URL | https://documenter.getpostman.com/view/21863361/2s83tCKYRA (opens in a new tab) |
---|
REFUND
{
"token": ""
};
{
"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)
}
}
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
},
...
]
}
{
"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
URL | https://documenter.getpostman.com/view/21863361/2s83tCKYRA (opens in a new tab) |
---|
TICKET
{
"token": ""
};
{
"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)
}
}
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
},
...
]
}
{
"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
URL | https://documenter.getpostman.com/view/21863361/2s83tCKYRA (opens in a new tab) |
---|
TIP ADJUST
{
"token": ""
};
{
"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
}
}
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
},
...
]
}
{
"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
URL | https://documenter.getpostman.com/view/21863361/2s83tCKYRA (opens in a new tab) |
---|
ZERO DOLLAR TIP ADJUST
{
"token": ""
};
{
"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
}
}
{
"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
{
"merchantAuthentication": {
"merchantId": "962923571839",
"transactionReferenceId": "87813a46a578216876a3"
},
"transactionRequest": {
"transactionType": 8,
"amount": "500",
"rrn": "412308501306"
},
"preferences": {
"eReceipt": true,
"customerName": "Customer_Name",
"customerEmail": "Customer_Email",
"customerMobile": "+919030427945"
}
}
{
"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
{
"merchantAuthentication": {
"merchantId": "258823860131"
},
"transactionRequest": {
"transactionType": 9
}
}
{
"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
}
}
{
"iposhpresponse": {
"field": "IPOS_BATCH_001",
"message": "no open batch for this TPN"
}
}
BATCH SETTLEMENT
iPOSTransact API – Batch Settlement – JSON Request Sample
{
"token": ""
};
{
"merchantAuthentication": {
"merchantId": "",
"transactionReferenceId": ""
},
"transactionRequest": {
"transactionType": 4 // Batch settlement
}
}
iPOSTransact API – Batch Settlement – JSON Response Sample
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.transactionType",
"message": "Invalid Transaction Type"
},
...
]
}
{
"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)
Objects | Description |
---|---|
Sandbox URL * | https://payment.ipospays.tech/api/v3/iposTransact |
Production URL * | https://payment.ipospays.com/api/v3/iposTransact |
Version 2
Objects | Description |
---|---|
Sandbox URL * | https://payment.ipospays.tech/api/v2/iposTransact |
Production URL * | https://payment.ipospays.com/api/v2/iposTransact |
Version 1
Objects | Description |
---|---|
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
{
"token": ""
};
{
"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
}
}
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
},
...
]
}
{
"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
{
"token": ""
};
{
"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
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
}, ...
]
}
{
"iposhpresponse": {
"hostResponseCode": "00",
"message": "Approved",
"paymentMethod": "VOID SALE",
"transactionType": 11,
"amount": "1000",
"transactionId": "46882215670249370721746700140534",
"rrn": "z-H0Wd0kWgzRHov6wjTVpFVHEmaB6SXiyVoK"
}
}
REFUND
JSON Request Sample
{
"token": ""
};
{
"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
{
"errors": [
{
"field": "merchantAuthentication.merchantId",
"message": "Invalid Merchant Id"
},
{
"field": "transactionRequest.RRN",
"message": "Invalid RRN number"
}, ...
]
}
{
"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
{
"token": ""
};
{
"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"
}
}
{
"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:
{
"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:
{
"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.
{
"merchantAuthentication": {
"merchantId": "962923571839",
"transactionReferenceId": "transactionReferenceId or rrn or transactionId"
}
}
{
"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
{
"merchantAuthentication": {
"merchantId": "962923571839",
"transactionReferenceId": "3245623463254631S2343W12345354356" // Invalid ID
}
}
{
"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.
{
"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"
}
}
{
"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"
}
}
{
"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.