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

iPOS Transact API

Prerequisites

  • For Sandbox (UAT)

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

  • For Production (Live)

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

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

How to Generate an Auth Token

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

Supported Transaction Types

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

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

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

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

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

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

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

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

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

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

How to Use iPOS Transact API

For Sale / Pre-Auth Transactions

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

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

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

HPP APISPIn API

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

For Void / Refund Transactions

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

  • HPP or SPIn integration is not required.

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

End Points and Objects

Request Method

HTTPS Request MethodPOST

End Points

Version 2

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

Version 1

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

Request Parameters - Header Objects

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

Request Parameters - Body Objects

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

TPN number registered on the portal.

Example Value: 139322815010

Length: 12 digits

transactionReferenceId * string Required

Merchant's unique transaction reference ID.

Format: Alphanumeric

Length: Must be 20 characters or fewer.

transactRequest ( Obj )
amount * String Required

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

Length: 8 characters

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

RRN * Number Conditional

Unique retrieval reference number.

Length: 12 characters

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

transactionType * Number Required

Type of transaction to be processed.

Default: 1

Values:

1 – Sale (using card token)

5 – PreAuth (using card token).

10 - ACH (using achToken)

cardToken* * String Required

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

Format: Encrypted token string.

paymentTokenId * String Conditional

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

Format: Encrypted token string.

applySteamSettingTipFeeTax * String Required

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

Values: true or false

Default: false

Note:

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

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

achToken String Optional

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

Format: Unique token string

achTransactionId String Optional

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

Format : Transaction Id String

achProccessor Number Optional

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

Format : 1 - PAYA

preferences ( Obj )
eReceipt * Boolean Required

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

Values: true or false.

customerName String Optional

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

Format: Alphabets and spaces

Length: Up to 25 characters

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

customerEmail String Optional

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

Format: Valid email address

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

customerMobile String Optional

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

Format: +<country-code><number>

Example: +18989898989

Length: 13 characters

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

requestCardToken Boolean Optional

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

Values: true or false.

GooglePay Object Optional

Encrypted Request Received from Google under Dejavoo PSP Key.

Values : Encrypted Data from Google

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

requestAchToken Boolean Optional

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

AVS ( Obj - Use v2 version for this future )
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)

ObjectstypeDescription
totalAmount StringTotalAmount where we need to request for the processor to debit the amount from HSA Cards, Type : String, Value : 1200 Need to format as 12 * 100
prescriptionAmount StringPrescriptionAmount where we are sending the amount with PrescriptionAmount from HSA Cards, Value : 200 need to format as 2 * 100
dentalAmount StringDentalAmount where customers has came for dental specialist doctors service., Value : 100 need to format as 1 * 100
clinicAmount StringclinicAmount where customers came for clinical services., Value : 100 need to format as 1 * 100
opticalAmount StringopticalAmount needs to add if the customers came for Eye services. If opticalAmount is added then integrator should not add the totalAmount,prescriptionAmount,dentalAmount and clinicAmount., Value : 100 need to format as 1 * 100

Response Parameters

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

iPOS-Transact response code.

Values:

200 – Successful, 400 – Declined

responseMessage * string Required

iPOS-Transact response message.

Values: Successful, Declined

errResponseCode* * Alphanumeric Conditional

PG error response code.

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

Length: Up to 2 characters

Example: 00, 05, …

errResponseMessage* * string Conditional

PG error response message.

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

transactionReferenceId * string Required

Merchant's unique transaction reference ID.

Format: Alphanumeric

Length: Up to 20 characters

transactionType * Number Required

Type of transaction to be processed.

Values:

1 – Sale

2 – Void

3 – Refund

amount Float Required

Amount voided/refunded.

Format: xxxxxx.xx

responseApprovalCode string Optional

Response Approval Code.

Format: Alphanumeric

Length: 6 characters

RRN Number Required

Unique retrieval reference number.

Length: 12 characters

transactionId * Number Required

PG response unique transaction ID.

Length: 32 characters

transactionNumber Number Optional

Invoice or transaction number.

Length: 4 digits

batchNumber Number Optional

Batch number.

Length: 3 digits

totalAmount Float Optional

Total amount charged to the customer.

Format: xxxxxx.xx

Length: Up to 8 characters

customFee Float Optional

Custom fee charged to the customer.

Format: xxxxxx.xx

chdToken String Optional

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

Format: Alphanumeric

total_without_fee * Decimal Required

Total Amount without Fee

Values: 1.00

batch_number * String Required

Batch Number for Settlement Batch

Values: 423

batch_profiles Object Optional

Batch Profiles Data

withoutLocalTaxAmount Decimal Optional

Total Amount without Local Tax

Values: 1.00

without_tax Decimal Optional

Total Amount without Tax

Values: 1.00

batch_summary Object Optional

Batch Summary Information

inx String Optional

Batch Summary Index

Value : 1

amount Decimal Optional

Total Batch Settlement Amount

Value : 96.94

profileId String Optional

Profile Number Register with TPN

Value: 01

type * String required

Type of Transaction

Value: SALE

txName String Optional

Type of Transaction

Value: SALE

transaction_no Number Optional

Transaction Number

Value : 2

batch_number String Optional

Batch Number

Value : 2

fee Decimal Optional

Fee Amount

Value : 3.63

batch_details Object Optional

Batch Detail Information

surcharge Number Optional

Surcharge

reducedTaxFee String Optional

Reduced Tax Fee

groupType String Optional

Group Type

approvalCode String Optional

Transaction Approval Code

Value : TAS996

externalRefId String Optional

External Transaction Id

tagValue String Optional

Tag Value

discount Number Optional

Discount Amount

appCode String Optional

Transaction Approval Code

Value : TAS996

type String Optional

Transaction Type

Value : Sale

voidFlag String Optional

Void Status

Value : N/Y

posRequestTime String Optional

Transaction Request Time

invoiceNumber String Optional

Invoice Number

onlyTipAmt Number Optional

Tip Amount

customFee Number Optional

Custome Fee

approvedAmount Decimal Optional

Approved Txn Amount

commercialTaxAmount Number Optional

Commercial Tax Amount

reducedTax Number Optional

Reduced Tax Amount

tagLabel String Optional

Tag Label Value

serviceFee Decimal Optional

Service Fee Amount

amount Decimal Optional

Transaction Amount

tipAmount Decimal Optional

Tip Amount

merchantFee Decimal Optional

Merchant Fee

transactionId String Optional

Unique Transaction generated per Request

stateTaxAmount Decimal Optional

State Tax Amount

baseAmount Decimal Optional

Base Amount

rrn String Optional

Transaction Unique Number

localTaxAmount Decimal Optional

Local Tax Amount

feeAmount Decimal Optional

Fee Amount

profileId String Optional

Profile Id

adjustedTipAmount Decimal Optional

Adjusted Tip Amount

totalTaxAmount Decimal Optional

Total Tax Amount

posRequestDate String Optional

Pos Request Date

account String Optional

Transaction Initiated PAN

card String Optional

Card Type

discount Decimal Optional

Discount Amount

settleDate String Optional

Settled Date

batchBase Decimal Optional

Batch Base Amount

Batch Total Amount Decimal Optional

Discount Amount

stateTaxAmount Decimal Optional

State Tax Amount

withoutStateTaxAmount Decimal Optional

Without State Tax Amount

localTaxAmount Decimal Optional

Local Tax Amount

without_discount Decimal Optional

Without Discount

profile_name String Optional

Profile Name

without_tip String Optional

Without Tip Amount

profileCode String Optional

Profile Code

tip Decimal Optional

Tip Amount

without_fee Decimal Optional

Without Fee Amount

taxAmount Decimal Optional

Tax Amount

transaction_no Number Optional

Transaction Number

processorData Object Optional

Processor Information

Agent String Optional

Agent Number

Chain String Optional

Chain Number

TermNo String Optional

Terminal Number

Agent_FIID String Optional

Agent Id

Mid String Optional

Terminal Registered under Merchant Number

Store String Optional

Registered Store Number

dsGroup String Optional

Terminal Number

TermId String Optional

Registered under Bank

ABA_No String Optional

Bank routing number

total_transactions Number Optional

Number of transaction Settle

total_fee Decimal Optional

Total Fee Amount

cash_payment Object Optional

Cash Payment Transactions

data Object Optional

Cash Payment Transactions Data

cash_payment_total Number Optional

Total Cash Payments

cash_txn_count Number Optional

Total Cash Txn Count

alter_payments Object Optional

Alter Payment under TPN

alter_txn_count Number Optional

Alter Payment Txn Count

approvalCode String Optional

Approval Code

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

Sample Requests and Responses for Card

Sale

Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": 1, // Sale (using token)
        "amount": "", // Amount to be refunded, example 1000 for 10$ i.e. 10x100
        "cardToken": "", // Transactions initiated from iPOS Transact API (Optional for GooglePay and PaymentTokenId)
        “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>"
},
 
//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"
        },
        ...
    ]
}
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)

URLyet to share sandbox postman URL

Pre-Auth

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

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

URLyet to share sandbox postman URL

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

iPOSTransact API – (Postman) Simulator URL

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

Refund

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

iPOSTransact API – (Postman) Simulator URL

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

Ticket

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

iPOSTransact API – (Postman) Simulator URL

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

Tip Adjust

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

iPOSTransact API – (Postman) Simulator URL

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

Incremental Auth

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

Open Batch

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

Batch Settlement

iPOSTransact API – Batch Settlement – JSON Request Sample

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

iPOSTransact API – Batch Settlement – JSON Response Sample

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

iPOSTransact API – Batch Settlement Transaction (Postman URL)

URLyet to share sandbox postman URL

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": "1000",// Transaction Amount with be calculated as $10 means 1000
        "achProcessor" : 1,//PAYA-1        //Processor Value whether its PAYA or others 
"achToken":"05944FB3E1DA4663868455AF630F45BE"// Token received in webhooks or returnURL
    },
    "preferences": {
        "eReceipt": true,
        "customerEmail": "Customer_Email",// Customer Email Id
        "customerMobile": "+1234567891", // Customer Mobile Number
        "requestAchToken": true // true- Then it will share the achToken in Response if transaction is Approved. False - We will not share the achToken
    }
}
Transact API - JSON Response Sample
{
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
        {
            "field": "transactionRequest.RRN",
            "message": "Invalid RRN number"
        },
        ...
    ]
}
Payment Processor Response
{
    "iposhpresponse": {
        "hostResponseCode": "00",
        "message": "Approved",
	    "paymentMethod":"SALE",
        "transactionType": 10,
	    "amount":"10"
        "achToken": "05944FB3E1DA4663868455AF630F45BE",
        "transactionId": "35999115670249370721746687387468",
        "rrn": "BT_-868Igb-q5sZ_AW34BvvAcmy6f-aadqAN"
    }
}

Void

JSON Request Sample

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

Transact API -JSON Response Sample

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

Refund

JSON Request Sample

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

Transact API -JSON Response Sample

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

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 Tokenization