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.

Card Token Usage

  1. Sale Transactions:

  • To use a card token for sale transactions, integration with HPP or SPIn API is mandatory.

  • If you’ve already implemented HPP or SPIn API using the same TPN, you cannot create a new token. You must reuse the token generated by the HPP or SPIn API.

  1. Void and Refund Transactions:

  • If you are implementing the iPOS Transact API only for void and refund transactions, HPP API is not required.

  • Instead, you need to generate a new ECOM token and use it in the iPOS Transact API.

Parameters Required for Transactions

  1. Void and Refund Transactions:

To process void or refund payments, the following details are required:

  • TPN Number
  • RRN Number (Retrieval Reference Number): Available on the receipt of the sale.
  • Amount: Mandatory for partial refunds.
  1. Sale Transactions Using Card Token:

To perform sale transactions with a card token, you need:

  • TPN Number
  • Card Token
  • Amount
IndicatorDescription
* Mandatory
** Required only under specific conditions.

Supported Transaction Types

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

  1. Sale
  2. Pre Auth
  3. Void
  4. Refund
  5. Ticket
  6. Tip Adjust
  7. Incremental Auth
  8. Open Batch
  9. Batch Settlement

Transaction Type: Sale/PreAuth (Using Card Token/Payment Token/GooglePay)

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. This feature is handy for businesses that need to collect an upfront payment. The amount held in Pre Auth can be retrieved by performing a Ticket transaction.

For example, hotels use this type of transaction to collect an amount from guests and later add taxes, fees, and tips for any additional purchases or services during their stay. These additional charges are combined with the initial amount during checkout.

ipos-transact API request contains 3 primary objects

ObjectsDescription
Token Required: Contains AuthToken information to be included in the request header.
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.

Request Method

HTTPS Request MethodPOST

iposTransact API Endpoint

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

Request Parameters

  • Request Parameters (Header)
ObjectsDescription
token AuthToken (can be obtained from portal settings).
JSON Content-Type application/json
  • Request Parameters (Body)
FieldTypeDescription
merchantAuthentication ( Obj )
merchantId * Number

TPN number registered on the portal.

Example Value: 139322815010

Length: 12 digits

transactionReferenceId * string

Merchant's unique transaction reference ID.

Format: Alphanumeric

Length: Must be 20 characters or fewer.

transactRequest ( Obj )
amount String

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

Length: 8 characters

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

transactionType * Number

Type of transaction to be processed.

Default: 1

Values:

1 – Sale (using card token)

5 – PreAuth (using card token).

cardToken* * String

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

Format: Encrypted token string.

paymentTokenId* * String

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

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.

preferences ( Obj )
eReceipt * Boolean

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

Values: true or false.

customerName String

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

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

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

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

Values: true or false.

GooglePay String

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

AVS ( Obj - Use v2 version for this future )
StreetNo String

Street number of the customer's address.

Zip String

Zip code of the customer’s address.

Response Parameters

FieldTypeDescription
iPOS-TransactResponse ( Obj )
responseCode * Number

iPOS-Transact response code.

Values:

200 – Successful, 400 – Declined

responseMessage * string

iPOS-Transact response message.

Values: Successful, Declined

errResponseCode* * Alphanumeric

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

PG error response message.

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

transactionReferenceId * string

Merchant's unique transaction reference ID.

Format: Alphanumeric

Length: Up to 20 characters

transactionType * Number

Type of transaction to be processed.

Values:

1 – Sale

2 – Void

3 – Refund

amount Float

Amount voided/refunded.

Format: xxxxxx.xx

responseApprovalCode string

Response Approval Code.

Format: Alphanumeric

Length: 6 characters

RRN Number

Unique retrieval reference number.

Length: 12 characters

transactionId * Number

PG response unique transaction ID.

Length: 32 characters

transactionNumber Number

Invoice or transaction number.

Length: 4 digits

batchNumber Number

Batch number.

Length: 3 digits

totalAmount Float

Total amount charged to the customer.

Format: xxxxxx.xx

Length: Up to 8 characters

customFee Float

Custom fee charged to the customer.

Format: xxxxxx.xx

chdToken String

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

Format: Alphanumeric

iposTransact API – Sale using Token – JSON Request Sample

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>"
}

iposTransact API – Sale using Token – 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 - Upon sale transaction success or decline

{
    "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)

URLyet to share sandbox postman URL

Transaction Type: Void | Refund | Ticket and Tip Adjust

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

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

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

  • Tip Adjust enables users to modify the tip amount on a transaction before the batch is settled and sent to the processor. This feature is available only if the tip option is enabled for the TPN on the portal.

ipos-transact API request contains 3 primary objects

ObjectsDescription
Token Required: Includes the AuthToken information to be sent in the request header.
merchantAuthentication Required: Contains merchant authentication details, such as the TPN number and a unique transaction reference ID.
transactRequest Required: Includes details such as transaction type, RRN, and the amount for processing payments, voids, or refunds.

Request Method

HTTPS Request MethodPOST

iposTransact API Endpoint

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

Request Parameters

Request Parameters (Header)

ObjectsDescription
token AuthToken. It can be generated in the Settings section of the portal.
JSON Content-Type application/json

Request Parameters (Body)

FieldTypeDescription
merchantAuthentication ( Obj )
merchantId * Number

TPN number registered on the portal.

TPN Number registered in iPOS.

Example Value: 139322815010

Length: 12 digits

transactionReferenceId * string

Merchant's unique transaction reference ID.

Format: Alphanumeric

Length: ≤ 20 characters

transactRequest ( Obj )
amount String

Amount (in USD) to be voided or refunded. This amount can be equal to or less than the settled amount.

Details: Multiply the USD amount by 100.

Length: Up to 8 characters

Format: 12525 (for $125.25 × 100)

RRN * Number

Unique retrieval reference number.

Length: 12 characters

transactionType * Number

The type of transaction to be processed.

Default: 3 Values:

1 – Sale

2 – Void

3 – Refund

6- Ticket

7-TipAdjust

Response Parameters

FieldTypeDescription
iPOS-TransactResponse ( Obj )
responseCode * Number

iPOS-Transact response code

Values: 200 – Successful

400 – Declined

responseMessage * string

iPOS-Transact response message

Values: Successful, Declined

errResponseCode* * Alphanumeric

PG error response code or payment processor error response code.

Values: PG error response code or payment processor error response code (e.g., 00, 05, etc.).

Length: Up to 2 characters

Note: Error code & message details are shared at the end of this document.

errResponseMessage* * string

PG error response message or payment processor error response message.

Values: PG error response message / Payment processor error response message

Note: Error code & message details are shared at the end of this document.

transactionReferenceId * string

Merchant unique transaction reference id

Format: Alphanumeric

Length: <=20 chars required

transactionType * Number

Type of transactions to be processed.

Note: 1 – sale, 2 – void, 3 – refund

amount Float

Amount voided/refunded

Format: xxxxxx.xx

responseApprovalCode string

Response Approval Code

Format: Alphanumeric

Length: 6 chars

RRN Number

Unique retrieval reference number

Length: 12 characters

transactionId * Number

PG response unique transaction id

Length: 32 characters

transactionNumber Number

Invoice of Transaction number

Length: 4 digits

batchNumber Number

Batch Number

Length: 3 digits

iposTransact API – JSON Request Sample

Post head request (header auth-token request)
{
    "token": ""
};
Post body request
{
    "merchantAuthentication": {
        "merchantId": "",
        "transactionReferenceId": ""
    },
    "transactionRequest": {
        "transactionType": <2-void / 3-refund / 6-ticket, 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 – 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 - 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, 3 - refund, 6 - ticket, 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)

Transaction Type: 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. This is especially useful in dynamic environments like bars or restaurants, where customer spending may fluctuate. Merchants can add up to five incremental auth, where each increment will be added to the original Pre-Auth amount

Use Case Example:

Imagine a customer at a bar buys drinks and the merchant performs a Pre Auth transaction of $50 for their drinks. Throughout the evening, they order more, and their bill exceeds the pre-authorized amount. Traditionally, the merchant would have to void the original transaction and start a new one for the higher total. With Incremental Auth, the merchant can simply increase the authorized amount without interrupting the payment process or causing inconvenience to the customer.

ObjectsDescription
Token Required: Includes the AuthToken information to be sent in the request header.
merchantAuthentication Required: Contains merchant authentication details, such as the TPN number and a unique transaction reference ID.
transactRequest Required: Includes details such as transaction type

Request Method

HTTPS Request MethodPOST

iposTransact API Endpoint

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

Request Parameters

Request Parameters (Header)

ObjectsDescription
token AuthToken. It can be generated in the Settings section of the portal.
JSON Content-Type application/json

Request Parameters (Body)

FieldTypeDescription
merchantAuthentication ( Obj )
merchantId * Number

TPN Number registered on the portal.

Length: 12 digits

Example Value: 139322815010

transactRequest ( Obj )
amount Number

Request amount for Incremental Auth

RRN Number

Original Pre Auth RRN number

transactionType * Number

The type of transaction to be processed.

Default: 4

Values:

4 – Batch Settlement

preferences ( Obj )
eReceipt * Boolean

Request amount for Incremental Auth

customerName String

Original Pre Auth RRN number

customerEmail String

The type of transaction to be processed.

Default: 4

Values:

4 – Batch Settlement

customerMobile String

The type of transaction to be processed.

Default: 4

Values:

4 – Batch Settlement

Response Parameters

FieldTypeDescription
iPOS-TransactResponse ( Obj )
responseCode * Number

iPOS-Transact response code

Values: 200 – Successful

400 – Declined

responseMessage * string

iPOS-Transact response message

Values: Successful, Declined

errResponseCode* * Alphanumeric

PG error response code

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

Length: Up to 2 characters

Processor Response Code: 2 characters.

Example: 00, 05, …

Note: Error code & message details are shared at the end of this document.

errResponseMessage* * string

PG error response message

Values: PG error response message / Payment processor error response message

transactionReferenceId * string

Merchant's unique transaction reference ID.

Format: Alphanumeric

Length: <=20 characters required

transactionType * Number

Type of transactions to be processed.

Values:

1 – sale

2 – void

3 – refund

amount Float

Amount voided/refunded

Format: xxxxxx.xx

responseApprovalCode string

Response Approval Code

Format: Alphanumeric

Length: 6 characters

RRN Number

Unique retrieval reference number

Length: 12 characters

transactionId * Number

PG response unique transaction id

Length: 32 characters

transactionNumber Number

Invoice of Transaction number

Length: 4 digits

batchNumber Number

Batch Number

Length: 3 digits

Request Body
{
    "merchantAuthentication": {
        "merchantId": "962923571839",
        "transactionReferenceId": "87813a46a578216876a3"
    },
    "transactionRequest": {
        "transactionType": 8,
        "amount": "500",
        "rrn": "412308501306"
    },
    "preferences": {
        "eReceipt": true,
        "customerName": "Sujith",
        "customerEmail": "schennur@denovosystem.com",
        "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": ""
    }
}

Transaction Type: 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.

ObjectsDescription
Token Required: Includes the AuthToken information to be sent in the request header.
merchantAuthentication Required: Contains merchant authentication details, such as the TPN number and a unique transaction reference ID.
transactRequest Required: Contains details such as transaction type, RRN, and amount for processing void or refund.

Request Method

HTTPS Request MethodPOST

iposTransact API Endpoint

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

Request Parameters

Request Parameters (Header)

ObjectsDescription
token AuthToken. It can be generated in the Settings section of the portal.
JSON Content-Type application/json

Request Parameters (Body)

FieldTypeDescription
merchantAuthentication ( Obj )
merchantId * Number

TPN Number registered on the portal.

Length: 12 digits

Example Value: 139322815010

transactRequest ( Obj )
transactionType * Number

The type of transaction to be processed.

Default: 9

Values:

9 – Open Batch

Response Parameters

FieldTypeDescription
iPOS-TransactResponse ( Obj )
total_without_fee * Decimal

Total Amount without Fee

Values: 1.00

batch_number * String

Batch Number for Settlement Batch

Values: 423

batch_profiles Object

Batch Profiles Data

withoutLocalTaxAmount Decimal

Total Amount without Local Tax

Values: 1.00

without_tax Decimal

Total Amount without Tax

Values: 1.00

batch_summary Object

Batch Summary Information

inx String

Batch Summary Index

Value : 1

amount Decimal

Total Batch Settlement Amount

Value : 96.94

profileId String

Profile Number Register with TPN

Value: 01

type * String

Type of Transaction

Value: SALE

txName String

Type of Transaction

Value: SALE

transaction_no Number

Transaction Number

Value : 2

batch_number String

Batch Number

Value : 2

fee Decimal

Fee Amount

Value : 3.63

batch_details Object

Batch Detail Information

surcharge Number

Surcharge

reducedTaxFee String

Reduced Tax Fee

groupType String

Group Type

approvalCode String

Transaction Approval Code

Value : TAS996

externalRefId String

External Transaction Id

tagValue String

Tag Value

discount Number

Discount Amount

appCode String

Transaction Approval Code

Value : TAS996

type String

Transaction Type

Value : Sale

voidFlag String

Void Status

Value : N/Y

posRequestTime String

Transaction Request Time

invoiceNumber String

Invoice Number

onlyTipAmt Number

Tip Amount

customFee Number

Custome Fee

approvedAmount Decimal

Approved Txn Amount

commercialTaxAmount Number

Commercial Tax Amount

reducedTax Number

Reduced Tax Amount

tagLabel String

Tag Label Value

serviceFee Decimal

Service Fee Amount

amount Decimal

Transaction Amount

tipAmount Decimal

Tip Amount

merchantFee Decimal

Merchant Fee

transactionId String

Unique Transaction generated per Request

stateTaxAmount Decimal

State Tax Amount

baseAmount Decimal

Base Amount

rrn String

Transaction Unique Number

localTaxAmount Decimal

Local Tax Amount

feeAmount Decimal

Fee Amount

profileId String

Profile Id

adjustedTipAmount Decimal

Adjusted Tip Amount

totalTaxAmount Decimal

Total Tax Amount

posRequestDate String

Pos Request Date

account String

Transaction Initiated PAN

card String

Card Type

discount Decimal

Discount Amount

settleDate String

Settled Date

batchBase Decimal

Batch Base Amount

Batch Total Amount Decimal

Discount Amount

stateTaxAmount Decimal

State Tax Amount

withoutStateTaxAmount Decimal

Without State Tax Amount

localTaxAmount Decimal

Local Tax Amount

without_discount Decimal

Without Discount

profile_name String

Profile Name

without_tip String

Without Tip Amount

profileCode String

Profile Code

tip Decimal

Tip Amount

without_fee Decimal

Without Fee Amount

taxAmount Decimal

Tax Amount

transaction_no Number

Transaction Number

processorData Object

Processor Information

Agent String

Agent Number

Chain String

Chain Number

TermNo String

Terminal Number

Agent_FIID String

Agent Id

Mid String

Terminal Registered under Merchant Number

Store String

Registered Store Number

dsGroup String

Terminal Number

TermId String

Registered under Bank

ABA_No String

total_transactions Number

Number of transaction Settle

total_fee Decimal

Total Fee Amount

cash_payment Object

Cash Payment Transactions

data Object

Cash Payment Transactions Data

cash_payment_total Number

Total Cash Payments

cash_txn_count Number

Total Cash Txn Count

alter_payments Object

Alter Payment under TPN

alter_txn_count Number

Alter Payment Txn Count

approvalCode String

Approval Code

txTimeq String

Transaction Time

DiscountFee Decimal

Discount Fee

createdAt String

Transaction Requested Date

posResponseCode String

Pos Response Code

invoiceNumber String

Invoice Number

onlyTipAmt Decimal

Tip Amount

cashDiscount Decimal

Cash Discount Amount

txName String

Transaction Name

updatedAt String

Transaction Response Updated Date

serviceFee String

Service Fee Amount

hostResponseCode String

Host Response Code

maskedPan String

Masked PAN number

additionalDetails String

Additional Details

transactionId String

Transaction Id generated per request

destType String

Destination Name

txAmount Decimal

Transaction Amount

rrn String

Unique Transaction Number from Processor

transactionType Decimal

Type of Transaction

totalAmount Decimal

Total Amount

tpn String

Merchant Id

sourceType String

Requested Source Name

commonMode String

Mode of Request Received

txDate String

Transaction Date

alter_payment_total Decimal

Alter Payments Total Amount

total_tip Decimal

Total Tip Amount

batch_total Decimal

Batch Total Amount

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"
    }
}

Transaction Type: Batch Settlement

At the end of the business hours, when a merchant is ready to close, all transactions processed during their operating hours must be submitted to the processor to ensure the funds are transferred to their bank account.

A batch is a collection of transactions that have been processed but not yet settled. When a transaction is approved, it is added to the batch. If the batch has not yet been settled, it is considered an open batch. Transactions within an open batch can still be voided or reversed if necessary.

ipos-transact API request contains 3 primary objects

ObjectsDescription
Token Required: Includes the AuthToken information to be sent in the request header.
merchantAuthentication Required: Contains merchant authentication details, such as the TPN number and a unique transaction reference ID.
transactRequest Required: Includes details such as transaction type

Request Method

HTTPS Request MethodPOST

iposTransact API Endpoint

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

Request Parameters

Request Parameters (Header)

ObjectsDescription
token AuthToken. It can be generated in the Settings section of the portal.
JSON Content-Type application/json

Request Parameters (Body)

FieldTypeDescription
merchantAuthentication ( Obj )
merchantId * Number

TPN Number registered on the portal.

Length: 12 digits

Example Value: 139322815010

transactionReferenceId * string

Merchant's unique transaction reference ID.

Format: Alphanumeric

Length: ≤ 20 characters

transactRequest ( Obj )
transactionType * Number

The type of transaction to be processed.

Default: 4

Values:

4 – Batch Settlement

Response Parameters

FieldTypeDescription
iPOS-TransactResponse ( Obj )
responseCode * Number

iPOS-Transact response code

Values: 200 – Successful

400 – Declined

responseMessage * string

iPOS-Transact response message

Values: Successful, Declined

errResponseCode* * Alphanumeric

PG error response code

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

Length: Up to 2 characters

Processor Response Code: 2 characters.

Example: 00, 05, …

Note: Error code & message details are shared at the end of this document.

errResponseMessage* * string

PG error response message

Values: PG error response message / Payment processor error response message

transactionReferenceId * string

Merchant's unique transaction reference ID.

Format: Alphanumeric

Length: <=20 chars required

transactionType * Number

Type of transactions to be processed.

Values:

1 – sale

2 – void

3 – refund

amount Float

Amount voided/refunded

Format: xxxxxx.xx

responseApprovalCode string

Response Approval Code

Format: Alphanumeric

Length: 6 characters

RRN Number

Unique retrieval reference number

Length: 12 characters

transactionId * Number

PG response unique transaction id

Length: 32 characters

transactionNumber Number

Invoice of Transaction number

Length: 4 digits

batchNumber Number

Batch Number

Length: 3 digits

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

Error Response Code & Messages

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

Error Codes & Messages
iPOS TransactOnboard Merchant