Skip to main content

Finance API

The Finance API allows you to access finance details and lists, and manage invoices, credit, and payment.

This page covers the methods and endpoints associated with finance operations.

For more information on financial operations see the following Help Center articles:

Authentication​

Use the following header parameters for all requests:

Headers
Authentication
string required		Authentication bearer token.
See Sign up and authenticate.
X-IAA-OW-ID
integer required		Organization Workspace ID header.

Finance details​

Get Customer finance details​

GET

Get an overview of a Customer's finance details.

Query parameters
owId
integer		Organization Workspace ID.
isFinanceRequest
boolean		Represents whether request came from finance tab in Customer app.
For Customer Management Tab: false.
For Finance Tab: true.
year
integer		Year for data.
Response properties
pendingCampaigns
integer		Number of campaigns in pending status (see Campaign API guidelines for more info on statuses).
runningCampaigns
integer		Number of campaigns in running status (see Campaign API guidelines for more info on statuses).
totalCampaigns
integer		Total number of campaigns associated with Customer.
dataCost
integer		Data cost applied on campaigns of a given Customer.
actualSpent
integer		Amount of media spending by Customer.
credits
integer		Customer credits.
balance
integer		Funds balance of Customer.
spent
integer		Total campaign spending (media and data) by Customer.
earning
integer		Earnings made by Organization.
Response 200
{
    "success": true,
    "data": {
        "pendingCampaigns": 15,
        "runningCampaigns": 10,
        "totalCampaigns": 48,
        "dataCost": 0,
        "actualSpent": 0,
        "credits": 0,
        "balance": 30430.75,
        "spent": 0,
        "earning": 0
    }
}

Get Customer margin details​

GET

Get Customer margin details by margin type.

Query parameters
marginTypeIds
string		Margin type ID.
1: Gross margin.
owId
integer		Organization Workspace ID.
Response properties
marginTypeId
integer		Margin type ID.
1: Gross margin.
marginType
string		Type of margin calculated or applied.
marginValue
integer		The value set for the requested margin type for the Customer.
isBidShadingEnabled
boolean		Indicates if bid shading is enabled.
Response 200
{
    "success": true,
    "data": {
        "totalRecords": 1,
        "data": [
            {
                "marginTypeId": 1,
                "marginType": "Gross Margin",
                "marginValue": 15
            }
        ],
        "filteredRecords": 1,
        "isBidShadingEnabled": false
    }
}

Update Customer margin details​

POST

Update a Customer's margin settings.

Request schema
owId
integer		Organization Workspace ID.
marginTypeId
integer		Margin type ID.
1: Gross margin.
marginValue
integer		The value set for the requested margin type for the Customer.
campaignId
integer		Campaign ID.
email
string		Email address.
username
string		Username.
workspaceMargin
integer		Workspace margin value.
organizationMargin
integer		Organization margin value.
Request sample
{
    "owId": 202318,
    "marginTypeId": 1,
    "marginValue": 15
}

Get Organization margin settings​

GET

Get margin settings for the Organization Workspace, including the default margin applied to newly onboarded Customers.

Response properties
totalRecords
integer		Total number of margin settings records.
filteredRecords
integer		Number of filtered records.
data
array		List of margin settings.
data object properties
marginTypeId
integer		Margin type ID.
1: Gross Margin.
marginType
string		Margin type name.
marginValue
integer		Margin value.
Response 200
{
    "success": true,
    "data": {
        "totalRecords": 2,
        "data": [
            {
                "marginTypeId": 1,
                "marginType": "Gross Margin",
                "marginValue": 20
            }
        ],
        "filteredRecords": 1
    }
}
More responses
Response 403
{
    "success": false,
    "errorObjects": [
        {
            "error": "User is not allowed to access this api"
        }
    ]
}

Update Organization margin settings​

POST

Update margin settings for the Organization Workspace. For example, set a default margin to be applied to newly onboarded Customers.

Request schema
marginTypeId
integer		Margin type ID.
1: Gross margin.
marginValue
integer		Margin value (between 1 and 99).
Response properties
success
boolean		Indicates successful update: true.
data
string		Success message.
Request sample
{
    "marginTypeId": 1,
    "marginValue": 10
}
Response 200
{
    "success": true,
    "data": "Margin settings updated successfully."
}
More responses
Response 403
{
    "success": false,
    "errorObjects": [
        {
            "error": "User is not allowed to access this api"
        }
    ]
}
Response 422
{
    "success": false,
    "errorObjects": [
        {
            "error": "Invalid marginTypeId : 2"
        }
    ]
}

Campaign margin details​

GET

Get a list of campaign margin details.

Query parameters
owId
integer		Organization Workspace ID.
searchField
string		Filter results by search field.
isEdit
boolean		Indicates if user has edit access for the requested resources.
Response properties
campaignId
integer		Campaign ID.
campaignName
string		Campaign name.
status
string		Campaign status.
creativeTypeId
string		Creative type ID.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
campaignMargin
integer		Campaign margin.
isDefault
boolean		Indicates whether the campaign is using the Organization's default margin (true) rather than a campaign-specific override (false).
Response 200
{
  "success": true,
  "data": {
    "data": [
      {
        "campaignId": 192476,
        "campaignName": "Start_Track_Reach2",
        "status": "running",
        "creativeTypeId": 13,
        "campaignMargin": 0,
        "isDefault": false
      }
    ],
    "totalRecords": 1,
    "filteredRecords": 1
  }
}

Get Customer PG fees details​

GET

Get details for Customer PG fees.

Path parameters
owId
integer		Organization Workspace ID.
Response properties
organizationPgFeesDetails
object		Organization PG fees details.
organizationPgFeesDetails object properties
pgCampaignFees
integer		PG campaign fees.
pgWorkspaceShare
integer		PG Workspace share.
Response 200
{
    "success": true,
    "data": {
        "organizationPgFeesDetails": {
            "pgCampaignFees": 10,
            "pgWorkspaceShare": 15
        }
    }
}

Edit Customer PG fees​

PATCH

Update a Customer's PG fees details.

Path parameters
customerOwId
integer		Customer Organization Workspace ID.
Request schema
owId
integer		Organization Workspace ID.
pgCampaignFees
integer		PG campaign fees.
pgWorkspaceShare
integer		The share of PG fees applied to the campaign by the Workspace.
Response properties
success
boolean		Indicates Customer was successfully updated: true.
data
string		Success message.
Request sample
{
    "owId": 202318,
    "pgCampaignFees": 10,
    "pgWorkspaceShare": 15
}
Response 200
{
    "success": true,
    "data": "PG Fees details updated Successfully."
}

Get Customer Insights fees details​

GET

Get Insights fees details for a Customer. If type is provided, fetches for that specific report type; otherwise, fetches for all types.

Path parameters
customerOwId
integer		Customer Organization Workspace ID.
Query parameters
type
string optional		Insights report type, supported values: vld, pld, sls, aqs, ict, nld.
If not provided, returns all applicable types for the Customer's vertical.
Response properties
owId
integer		Customer Organization Workspace ID.
categories
object		Map of Insights category names to their fee details.
categories object properties
rate
number		Rate for the Insights report.
enabled
boolean		Whether the category is enabled.
markupType
string		Markup type: Absolute or Percentage.
markupTypeId
integer		Markup type ID.
markupValue
number		Markup value.
Response 200
{
    "success": true,
    "data": {
        "owId": 201427,
        "categories": {
            "nld": {
                "rate": 5.5,
                "enabled": true,
                "markupType": "Percentage",
                "markupTypeId": 2,
                "markupValue": 55.5
            },
            "ict": {
                "rate": 5.5,
                "enabled": true,
                "markupType": "Percentage",
                "markupTypeId": 2,
                "markupValue": 55.5
            },
            "pld": {
                "rate": 5.5,
                "enabled": true,
                "markupType": "Percentage",
                "markupTypeId": 2,
                "markupValue": 55.5
            },
            "vld": {
                "rate": 5.5,
                "enabled": true,
                "markupType": "Percentage",
                "markupTypeId": 2,
                "markupValue": 55.5
            },
            "sls": {
                "rate": 5.5,
                "enabled": true,
                "markupType": "Percentage",
                "markupTypeId": 2,
                "markupValue": 55.5
            },
            "aqs": {
                "rate": 5.5,
                "enabled": true,
                "markupType": "Percentage",
                "markupTypeId": 2,
                "markupValue": 55.5
            }
        }
    }
}

Update Customer Insights fees details​

PATCH

Update Insights fees for a specific category for a Customer.

Path parameters
customerOwId
integer		Customer Organization Workspace ID.
Request schema
category
string required		Insights report type category. Valid values: pld, vld, ict, sls, aqs, nld.
rate
number		Rate for the Insights report.
enabled
boolean		Enable or disable the report.
markupType
string		Markup type: Absolute or Percentage.
markupTypeId
integer		Markup type ID.
markupValue
number		Markup value.
Response properties
id
integer		Updated record ID.
message
string		Success message.
Request sample
{
    "category": "pld",
    "rate": 11,
    "enabled": true,
    "markupType": "Percentage",
    "markupTypeId": 2,
    "markupValue": 55.5
}
Response 200
{
    "success": true,
    "data": {
        "id": 1,
        "message": "Rate updated successfully. The new rate applies only to newly created reports"
    }
}
Response 200
{
    "success": true,
    "data": {
        "id": 6,
        "message": "Insights enabled successfully."
    }
}

Get Customer DoubleVerify details​

GET

Super Organization users can fetch the DoubleVerify Fraud & IVT Segments flag for a Customer Organization.

Query parameters
customerOwId
integer		Customer Organization Workspace ID.
Response properties
customerOwId
integer		Customer Organization Workspace ID.
isDvIvtSegmentsEnabled
boolean		Boolean flag to enable or disable free DV-IVT Segments for Advertiser/Customer.
Response 200
{
  "success": true,
  "data": {
    "customerOwId": 1,
    "isDvIvtSegmentsEnabled": true
  }
}
More responses
Response 422
{
  "success": true,
  "data": {
    "success": false,
    "errorObjects": [
      {
        "error": "User is not allowed to access provided customer details"
      }
    ]
  }
}

Update Customer DoubleVerify​

PATCH

Super Organization users can update the DoubleVerify IVT free Segments boolean flag for a Customer Organization.

Query parameters
customerOwId
integer		Customer Organization Workspace ID.
isDvIvtSegmentsEnabled
boolean		Boolean flag to enable or disable free DV-IVT Segments for Advertiser/Customer.
Response properties
customerOwId
integer		Customer Organization Workspace ID.
isDvIvtSegmentsEnabled
boolean		Boolean flag to enable or disable free DV-IVT Segments for Advertiser/Customer.
message
string		Success message.
Response 200
{
  "success": true,
  "data": {
    "customerOwId": 1,
    "isDvIvtSegmentsEnabled": true,
    "message": "DV Fraud & IVT segments enabled for free successfully"
  }
}
More responses
Response 422
{
  "success": true,
  "data": {
    "success": false,
    "errorObjects": [
      {
        "error": "User is not allowed to access provided customer details"
      }
    ]
  }
}

Get basic financial details​

GET
Response properties
paypalFeesPercentage
integer		PayPal fees percentage.
Response 200
{
    "success": true,
    "data": {
        "paypalFeesPercentage": 3.5
    }
}

Available balance​

GET

Get the available balance of the Workspace passed in the header or as a parameter based on the isCustomerRequest flag.

If isCustomerRequest flag is true then balance of the Customer Workspace will be returned. If the flag is false the balance of the Workspace passed in the header will be returned.

Query parameters
owId
integer		Organization Workspace ID.
isCustomerRequest
boolean		Customer app request (default): true.
Organization app request: false.
Response properties
success
boolean		Indicates successful retrieval of data.
data
integer		Available balance.
Response 200
{
    "success": true,
    "data": 5855904.72
}

Add ad serving cost​

POST

Add ad serving costs for a specific Customer. This endpoint is accessible only by Super Organization users.

Request schema
owId
integer		Customer Organization Workspace ID for whom the cost is being added.
imageCreativeCost
number		Ad serving cost for IQM hosted image creatives.
videoCreativeCost
number		Ad serving cost for IQM hosted video creatives.
audioCreativeCost
number		Ad serving cost for IQM hosted audio creatives.
Request sample
{
    "owId": 123456,
    "imageCreativeCost": 50.0,
    "videoCreativeCost": 100.0,
    "audioCreativeCost": 75.0
}
Response 200
{
    "success": true,
    "data": {
        "message": "Ad serving cost added successfully."
    }
}
More responses
Response 422
{
    "success": false,
    "errorObjects": [
        {
            "error": "User is not allowed to access provided customer details."
        }
    ]
}

Get ad serving cost​

GET

Get the ad serving cost details for a specific Customer.

Path parameters
customerOwId
integer		Customer Organization Workspace ID.
Response properties
owId
integer		Customer Organization Workspace ID.
adServingCostDetail
object		Ad serving cost details.
adServingCostDetail object properties
imageCreativeCost
number		Ad serving cost for IQM hosted image creatives.
videoCreativeCost
number		Ad serving cost for IQM hosted video creatives.
audioCreativeCost
number		Ad serving cost for IQM hosted audio creatives.
costConfigurationLevel
string		Level at which cost is configured (e.g., WORKSPACE).
msaConfigurationDetail
object		MSA configuration details.
Response 200
{
    "success": true,
    "data": {
        "owId": 201765,
        "adServingCostDetail": {
            "imageCreativeCost": 5,
            "videoCreativeCost": 5,
            "audioCreativeCost": 5,
            "costConfigurationLevel": "WORKSPACE",
            "msaConfigurationDetail": {
                "msaConfiguredWith": "MWS1",
                "logoURL": "https://iqm-host.com/avatar/MS.png"
            }
        }
    }
}
More responses
Response 422
{
    "success": false,
    "errorObjects": [
        {
            "error": "User is not allowed to access provided customer details."
        }
    ]
}

Add or update third party cost​

POST

Add or update third-party cost details. This endpoint is accessible only by Workspace Organization users.

If the Workspace user is setting or updating the cost for their own Workspace, the owId can be passed as null (it will be derived from the logged-in user context). For Advertiser-level cost configuration, owId must be provided explicitly.

Request schema
owId
integer		Organization Workspace ID of the Workspace or Advertiser (optional for Workspace self, required for Advertiser).
cost
number		Third-party cost value (range: greater than 0, up to 999).
Request sample (Advertiser)
{
    "owId": 123456,
    "cost": 150.0
}
Request sample (Workspace)
{
    "owId": null,
    "cost": 150.0
}
Response 200
{
    "success": true,
    "data": {
        "message": "3rd party cost added successfully."
    }
}
More responses
Response 422
{
    "success": false,
    "errorObjects": [
        {
            "error": "User is not allowed to access provided customer details."
        }
    ]
}

Get third party cost​

GET

Get the third-party cost details for a specific Customer. This endpoint is accessible only by Workspace and Super Organization types.

Path parameters
customerOwId
integer		Customer Organization Workspace ID.
Response properties
owId
integer		Customer Organization Workspace ID.
thirdPartyCostDetails
object		Third-party cost details (null if not configured).
thirdPartyCostDetails object properties
cost
number		Third-party cost value.
active
boolean		Indicates if the third-party cost is currently active.
Response 200 (Cost configured)
{
    "success": true,
    "data": {
        "owId": 123456,
        "thirdPartyCostDetails": {
            "cost": 4.2,
            "active": true
        }
    }
}
Response 200 (Cost not configured)
{
    "success": true,
    "data": {
        "owId": 123456,
        "thirdPartyCostDetails": null
    }
}

Disable third party cost​

PATCH

Disable an existing third-party cost configuration. This endpoint is accessible only by Workspace Organization users.

The third-party cost will be marked as inactive and the cost value set to null.

Path parameters
customerOwId
integer		Organization Workspace ID of the Workspace or Advertiser for which the third-party cost is being disabled.
Response 200
{
    "success": true,
    "data": {
        "message": "3rd party cost disabled successfully."
    }
}
More responses
Response 422
{
    "success": false,
    "errorObjects": [
        {
            "error": "User is not allowed to access provided customer details."
        }
    ]
}

Invoice management​

Get invoice for Organization​

GET

Get an invoice for an Organization.

Response properties
invoiceId
integer		Invoice ID.
owId
integer		Organization Workspace ID.
invoiceTitle
string		Invoice title.
invoiceCompanyName
string		Company name associated with invoice.
invoiceCompanyAddress
string		Address associated with company.
email
string		Company email.
website
string		Company website.
invoiceDescription
string		Invoice description.
paypalId
integer		PayPal ID.
chequeTransferId
integer		Cheque transfer ID.
wireTransferId
integer		Wire transfer ID.
termsAndConditions
string		Terms and conditions of invoice.
paymentTerm
string		Payment term of invoice.
Supported values
1Net 7
2Net 15
3Net 30
4Net 45
5Net 60
6Net 90
7Net 120
8Custom
invoiceFooter
string		Invoice footer details.
createdAt
string		Creation date of invoice.
Response 200
{
    "success": true,
    "data": {
        "invoiceId": 1,
        "owId": 334,
        "invoiceTitle": "The Alchemist",
        "invoiceCompanyName": "The Alchemist",
        "invoiceCompanyAddress": "42, 6th Avenue, New York, NY",
        "email": "shraddha.p+alchemist@iqm.com",
        "website": "www.alchemist.com",
        "invoiceDescription": "Dear Customer, Greetings from The Alchemist, we are writing to provide you an electronic invoice for your use of services.",
        "paypalId": 1,
        "chequeTransferId": 1,
        "wireTransferId": 2,
        "termsAndConditions": "Please make the payment in 30 days or your account might be put on hold",
        "paymentTerm": "30",
        "invoiceFooter": "The Alchemist | 12.234.56.789 | USA",
        "createdAt": "2021-08-27T07:33:14.000+00:00"
    }
}

Get invoice payment details​

GET

Get invoice payment details by invoice ID.

Query parameters
invoiceId
integer		Invoice ID.
Response properties
paypalPaymentDetail
object		PayPal payment details.
paypalPaymentDetail object properties
payPalId
integer		PayPal ID.
paypalAccountId
string		PayPal account ID.
chequePaymentDetail
object		Cheque payment details.
chequePaymentDetail object properties
chequeId
integer		Cheque ID.
chequeCompanyName
string		Company name.
chequeCompanyAddress
string		Company address.
wireTransferPaymentDetail
object		Wire transfer payment details.
wireTransferPaymentDetail object properties
wireTransferId
integer		Wire transfer ID.
wireTransferCompanyName
string		Company name.
bankName
string		Bank name.
accountNumber
string		Account number.
bankAddress
string		Bank address.
swiftCode
string		Swift code.
routing
string		Routing number.
Response 200
{
    "success": true,
    "data": {
        "paypalPaymentDetail": {
            "paypalId": 1,
            "paypalAccountId": "thealchemistfinance@paypal"
        },
        "chequePaymentDetail": {
            "chequeId": 1,
            "chequeCompanyName": "The Alchemist Company",
            "chequeCompanyAddress": "45, Fifth Avenue, NY, USA"
        },
        "wireTransferPaymentDetail": {
            "wireTransferId": 2,
            "wireTransferCompanyName": "The Alchemist",
            "bankName": "JP Morgan Chase Bank",
            "accountNumber": "670669295",
            "bankAddress": "498 7th Avenue New York NY",
            "swiftCode": "MGTCUS3G",
            "routing": "150098"
        }
    }
}

Get list of invoices for Customer or Organization​

GET

Get a list of invoices by Customer or Organization.

Path parameters
owId
integer		Organization Workspace ID.
Query parameters
status
string		Invoice status ID.
Supported values
1Pending
2Partially paid
3Unpaid
4Paid
5Overdue
7Processing
8Cancelled
sortBy
string		Sorts by ascending (+) or descending (-), default: -invoiceId.
Supported values: issuedOn, invoiceAmount, status.
paymentMode
integer		Payment mode filter.
Supported values
1PayPal
2Cheque
3Wire transfer
searchField
string		Search keyword to filter invoices.
limit
integer		Number of results per page.
pageNo
integer		Page number for pagination.
isCustomerRequest
boolean		(Organization endpoint only) Customer app request (default): true.
Organization app request: false.
Response properties
invoiceId
integer		Invoice ID.
invoiceFromDate
integer		Unix epoch timestamp of invoice start date, in milliseconds.
invoiceToDate
integer		Unix epoch timestamp of invoice end date, in milliseconds.
issuedOn
integer		Unix epoch timestamp of invoice issue date, in milliseconds.
invoiceAmount
integer		Invoice amount.
status
integer		Invoice status.
Supported values
1Pending
2Partially paid
3Unpaid
4Paid
5Overdue
7Processing
8Cancelled
paymentTerm
integer		Payment term.
Supported values
1Net 7
2Net 15
3Net 30
4Net 45
5Net 60
6Net 90
7Net 120
8Custom
paidAmount
integer		Paid amount.
paymentMode
array of integers		Payment mode.
Supported values
1PayPal
2Cheque
3Wire transfer
invoiceName
string		Invoice name.
actionNote
string		Action note.
invoiceStatusUpdatedBy
string		Name of who updated invoice status.
modifiedAt
integer		Unix epoch timestamp of modification date, in milliseconds.
Response 200
{
    "success": true,
    "data": {
        "data": [
            {
                "invoiceId": 79,
                "invoiceFromDate": 1601510400,
                "invoiceToDate": 1604102400,
                "issuedOn": 1632182400,
                "invoiceAmount": 553611.718,
                "status": 7,
                "paymentTerm": 30,
                "paidAmount": 5000,
                "paymentMode": [
                    2,
                    4
                ],
                "invoiceName": "Zydus - Oct2020",
                "actionNote": null,
                "invoiceStatusUpdatedBy": "Kartik Gevariya",
                "modifiedAt": 1632801378000
            }
        ],
        "totalRecords": 0,
        "filteredRecords": 0
    }
}

Update invoice settings​

PATCH

Update invoice settings details for an Organization.

Query parameter
isWhiteLabel
boolean		Set by Organization, must be set to true for invoice to be updated.
Request schema
invoiceTitle
string		Invoice title.
invoiceCompanyAddress
string		Invoice company address.
email
string		Email.
website
string		Website.
invoiceDescription
string		Invoice description.
termsAndConditions
string		Terms and conditions of invoice.
paymentTerm
string		Payment term ID.
Supported values
1Net 7
2Net 15
3Net 30
4Net 45
5Net 60
6Net 90
7Net 120
8Custom
invoiceFooter
string		Invoice footer details.
paypalAccountId
string		PayPal account ID.
chequeCompanyName
string		Company name on check (when payment mode type is check).
chequeCompanyAddress
string		Company address on check (when payment mode type is check).
wireTransferCompanyName
string		Company name for wire transfer (when payment mode type is wire transfer).
bankName
string		Bank name.
accountNumber
string		Account number.
bankAddress
string		Bank address.
companyTaxId
string		Company tax ID.
companyTaxName
string		Company tax name.
Response properties
invoiceId
integer		Invoice ID.
message
string		Success message.
Request sample
{
  "invoiceTitle": "The Alchemist",
  "invoiceCompanyAddress": "42, 6th Avenue, New York, NY",
  "email": "shraddha.p+alchemist@iqm.com",
  "website": "www.alchemist.com",
  "invoiceDescription": "Dear Customer, Greetings from The Alchemist, we are writing to provide you an electronic invoice for your use of services.",
  "termsAndConditions": "Please make the payment in 30 days or your account might be put on hold",
  "paymentTerm": "30",
  "invoiceFooter": "The Alchemist | 12.234.56.789 | USA",
  "paypalAccountId": "thealchemistfinance@paypal",
  "chequeCompanyName": "The Alchemist Company",
  "chequeCompanyAddress": "45, Fifth Avenue, NY, USA",
  "wireTransferCompanyName": "The Alchemist",
  "bankName": "JP Morgan Chase Bank",
  "accountNumber": "670669295",
  "bankAddress": "498 7th Avenue New York NY",
  "companyTaxId": "202130INGST",
  "companyTaxName": "GSTIN"
}
Response 200
{
  "success": true,
  "data": {
    "invoiceId": 1,
    "message": "Invoice details updated successfully"
  }
}
More responses
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invoice does not belong to the logged in organization workspace"
    }
  ]
}
Response
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invoice with the provided ID does not exists"
    }
  ]
}

Delete invoice tax data​

DELETE

Delete tax data for an invoice.

Query parameters
taxId
integer		Tax ID.
Response properties
success
boolean		Indicates successful deletion: true.
data
string		Success message.
Response 200
{
  "success": true,
  "data": "Tax data deleted successfully"
}
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Tax ID is invalid"
    }
  ]
}

Approve invoice​

PATCH

Approve an invoice by invoice ID with optional action note.

Path parameter
invoiceId
integer		Invoice ID.
Request schema
actionNote
string		Action note.
Response properties
success
boolean		Indicates successful approval.
data
string		Success message.
Request sample
{
  "actionNote": "Approved for payment"
}
Response 200
{
    "success": true,
    "data": "Invoice with the provided ID approved successfully"
}

Cancel invoice​

PATCH

Cancel an invoice by invoice ID with optional action note.

Path parameter
invoiceId
integer		Invoice ID.
Request schema
actionNote
string		Action note.
Response properties
success
boolean		Indicates successful cancellation: true.
data
string		Success message.
Request sample
{
  "actionNote": "Customer requested cancellation due to duplicate invoice"
}
Response 200
{
  "success": true,
  "data": "Invoice with the provided ID rejected successfully"
}

Mark invoice as paid​

POST

Pay an invoice by invoice ID. This endpoint also accepts query parameters as multipart/form-data along with paymentProof file upload.

Query parameters
invoiceId
integer required		Invoice ID.
owId
integer required		Organization Workspace ID.
paymentAmount
integer required		Payment amount.
paymentType
integer required		Payment type ID.
Supported values
1As fund
2Against invoice
3Refund
paymentDate
integer		Payment date as Unix epoch timestamp, in milliseconds (default: current date/time).
paymentMode
integer		Payment mode ID.
Supported values
1PayPal
2Cheque
3Wire transfer
transactionId
string		Transaction ID/reference number.
bankName
string		Bank name.
isCustomerRequest
boolean		Customer app request (default): true.
Organization app request: false.
Request schema
paymentProof
multipart/form-data optional		Payment proof file upload.
Response properties
success
boolean		Indicates successful invoice update: true.
data
string		Success message.
Request sample
curl -X POST "https://api.iqm.com/api/v3/fa/pay-invoice" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-IAA-OW-ID: 200001" \
  -H "Content-Type: multipart/form-data" \
  -F "invoiceId=12345" \
  -F "owId=200001" \
  -F "paymentAmount=1250.50" \
  -F "paymentDate=2025-10-07T12:00:00Z" \
  -F "paymentMode=2" \
  -F "transactionId=TXN-987654321" \
  -F "paymentType=1" \
  -F "bankName=First National Bank" \
  -F "isCustomerRequest=true" \
  -F "paymentProof=@/path/to/payment_receipt.pdf"

Response 200
{
    "success": true,
    "data": "Payment added Successfully."
}

Email invoice​

POST

Email an invoice to a specified email address.

Path parameter
owId
integer		Organization Workspace ID.
invoiceId
integer		Invoice ID.
Request schema
email
string		Email to send invoice to.
Response properties
success
boolean		Indicates email successfully sent: true.
data
string		Success message.
Request sample
{
    "email": "user@company.com"
}
Response 200
{
    "success": true,
    "data": "Invoice e-mail sent successfully."
}

Download invoice​

GET

Download a PDF invoice.

Path parameter
owId
integer		Organization Workspace ID.
invoiceId
integer		Invoice ID.
Query parameters
isCustomerRequest
boolean		Customer app request (default): true.
Organization app request: false.
Request sample
curl -X GET "https://api.iqm.com/api/v3/fa/download-invoice/{owId}/{invoiceId}?isCustomerRequest=true" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-IAA-OW-ID: 200001"

Get invoice template margin details​

GET

Get invoice template and margin configuration status for the specified Organization Workspace IDs, including whether margins are enabled and the parent Organization Workspace ID.

Query parameters
owIds
string required		Comma-separated list of Organization Workspace IDs.
Response properties
isParentInvoiceTemplateSet
boolean		Indicates whether the parent invoice template is set.
isMarginSet
boolean		Indicates whether margin settings are configured.
parentOWId
integer		Parent Organization Workspace ID.
Response 200
{
    "success": true,
    "data": {
        "isParentInvoiceTemplateSet": true,
        "isMarginSet": true,
        "parentOWId": 201186
    }
}

Get invoice template margin pre-requisite​

GET

Get pre-requisite details for invoice template margin settings, including whether a parent invoice template is set, and a list of Customers whose margins have not been configured.

Response properties
isParentInvoiceTemplateSet
boolean		Indicates whether the parent invoice template is set.
invoiceTemplateRequired
boolean		Indicates whether an invoice template is required.
organizationAppAccessible
boolean		Indicates whether the Organization app is accessible.
customerAppAccessible
boolean		Indicates whether the Customer app is accessible.
customerMarginList
array		List of Customers without margin settings configured.
customerMarginList object properties
owId
integer		Organization Workspace ID.
customerName
string		Customer name.
Response 200
{
    "success": true,
    "data": {
        "isParentInvoiceTemplateSet": true,
        "invoiceTemplateRequired": true,
        "organizationAppAccessible": true,
        "customerAppAccessible": true,
        "customerMarginList": [
            {
                "owId": 100002,
                "customerName": "Darshan Khatri"
            },
            {
                "owId": 100001,
                "customerName": "Bhaumik Shukla"
            }
        ]
    }
}

Credit management​

Credit summary​

GET

Get a credit summary by Organization Workspace ID.

Path parameter
owId
integer		Organization Workspace ID.
Query parameters
isCustomerRequest
boolean		Customer app request (default): true.
Organization app request: false.
Response properties
usedCredit
integer		Used credit amount.
totalCredit
integer		Total credit amount.
Response 200
{
    "success": true,
    "data": {
        "usedCredit": 21875.37,
        "totalCredit": 50000
    }
}

Offered credits​

GET

Get a list of offered credits to an Organization.

Query parameters
limit
integer		Number of entries returned per page, default: 50.
pageNo
integer		Page number of retrieved data, default: 1.
sortBy
string		Sorts by ascending (+) or descending (-), default: -modifiedAt.
Response properties
creditId
integer		Credit ID.
creditAmount
integer		Credit amount.
modifiedAt
string		Last modified date.
status
string		Status.
organizationName
string		Organization name.
Response 200
{
    "success": true,
    "data": {
        "data": [
            {
                "creditId": 2,
                "creditAmount": 1000,
                "modifiedAt": "2021-09-08T10:24:32.000+00:00",
                "status": "Unclaimed",
                "organizationName": "JP test org"
            },
            {
                "creditId": 1,
                "creditAmount": 1500,
                "modifiedAt": "2021-09-08T05:46:15.000+00:00",
                "status": "Revoked",
                "organizationName": "JP test org"
            }
        ],
        "totalRecords": 2,
        "filteredRecords": 2
    }
}

Customer credit list​

GET

Get a list of credits offered to a Customer.

Query parameters
owId
integer		Organization Workspace ID.
Response properties
creditId
integer		Credit ID.
owId
integer		Organization Workspace ID.
creditAmount
integer		Credit amount.
modifiedAt
string		Last modified date.
uowId
integer		User Organization Workspace ID.
displayName
string		Display name.
Response 200
{
  "success": true,
  "data": [
    {
      "creditId": 3,
      "owId": 54,
      "creditAmount": 1000,
      "status": "Revoked",
      "modifiedAt": "2021-09-03T04:23:41.000+00:00",
      "uowId": 1,
      "displayName": "IHP"
    },
    {
      "creditId": 2,
      "owId": 54,
      "creditAmount": 2000,
      "status": "Unclaimed",
      "modifiedAt": "2021-08-31T12:43:38.000+00:00",
      "uowId": 1,
      "displayName": "IHP"
    },
    {
      "creditId": 1,
      "owId": 54,
      "creditAmount": 6000,
      "status": "Unclaimed",
      "modifiedAt": "2021-08-31T12:12:43.000+00:00",
      "uowId": 1,
      "displayName": "IHP"
    }
  ]
}

Add credit to Customer​

POST

Add credit to a Customer's account.

Request schema
owId
integer		Organization Workspace ID.
creditAmount
integer		Credit amount to add.
Response properties
success
boolean		Indicates credit successfully added: true.
data
string		Success message.
Request sample
{
    "owId": 23,
    "creditAmount": 5000
}
Response 200
{
    "success": true,
    "data": "Credits offered Successfully."
}

Update credit offered to Customer​

PATCH

Update the credit offered to a Customer's account.

Request schema
owId
integer		Organization Workspace ID.
creditAmount
integer		Credit amount to add.
creditId
integer		Credit ID.
Response properties
success
boolean		Indicates credit successfully offered: true.
data
string		Success message.
Request sample
{
    "owId": 54,
    "creditAmount": 4000,
    "creditId": 3
}
Response 200
{
    "success": true,
    "data": "Credits updated Successfully."
}

Revoke credit offered to Customer​

POST

Revoke the credit offered to a Customer's account.

Request schema
owId
integer		Organization Workspace ID.
creditId
integer		Credit ID.
Response properties
success
boolean		Indicates credit successfully revoked: true.
data
string		Success message.
Request sample
{
    "owId": 54,
    "creditId": 2
}
Response 200
{
    "success": true,
    "data": "Credits revoked Successfully."
}

Claim offered credits​

POST

Claim the credits offered to a Customer's account.

Request schema
creditId
integer		Credit ID.
customerName
string		Customer Name.
businessName
string		Business Name.
taxId
string		Tax ID.
contactPersonName
string		Contact person name.
contactPersonEmail
string		Contact person email.
incorporationPlace
string		Incorporation location.
address
string		Address.
Response properties
success
boolean		Indicates credits successfully claimed: true.
data
string		Success message.
Request sample
{
    "creditId": 4,
    "customerName": "JP test ",
    "businessName": "JP test org3",
    "taxId": "123456",
    "contactPersonName": "JP",
    "contactPersonEmail": "jinesh.p+nonihpcust2@iqm.com",
    "incorporationPlace": "Gujarat, India",
    "address": "A-123, XYZ Complex, Ahmedabad, Gujarat, India - 380059"
}
Response 200
{
    "success": true,
    "data": "Credits claimed."
}

Payment management​

Get list of payment transactions for Organization​

GET

Get a list of payment transactions for an Organization.

Query parameters
status
string		Payment status ID.
Supported values
1Processing
2Paid
3Rejected
4Cancelled
paymentType
string		Payment type ID.
Supported values
1As fund
2Against invoice
3Refund
searchField
string		Filter results by search field.
limit
integer		Number of entries returned per page, default: 10.
pageNo
integer		Page number of retrieved data, default: 1.
Response properties
isPaymentInitiatorOrg
boolean		Indicates whether payment was created by logged-in Organization (true) or not (false).
paymentId
integer		Payment ID.
createdByUserEmail
string		Email of user who created payment.
paymentDate
integer		Unix epoch timestamp of payment date, in milliseconds.
paymentAmount
integer		Payment amount.
paymentStatus
string		Payment status.
Supported values
1Processing
2Paid
3Rejected
4Cancelled
paymentMode
string		Payment mode.
Supported values
1PayPal
2Cheque
3Wire transfer
paymentType
string		Payment type.
Supported values
1As fund
2Against invoice
3Refund
invoiceId
integer		Invoice ID.
modifiedAt
integer		Unix epoch timestamp of modification date, in milliseconds.
bankName
string		Bank associated with payment, if applicable, otherwise: null.
refundReason
string		Reason for refund, if applicable, otherwise: null.
Response 200
{
    "success": true,
    "data": {
        "data": [
            {
                "isPaymentInitiatorOrg": true,
                "paymentId": 19,
                "createdByUserEmail": "jinesh.p+nonihpcust2@iqm.com",
                "paymentDate": 1632076200000,
                "paymentAmount": 10000,
                "paymentStatus": "Rejected",
                "paymentMode": "PayPal",
                "paymentType": "As Fund",
                "invoiceId": 0,
                "modifiedAt": 1637566978000,
                "bankName": null,
                "refundReason": null
            },
            {
                "isPaymentInitiatorOrg": false,
                "paymentId": 886,
                "createdByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "paymentDate": 1635791400000,
                "paymentAmount": 10,
                "paymentStatus": "Processing",
                "paymentMode": "Check",
                "paymentType": "Refund",
                "invoiceId": 0,
                "modifiedAt": 1635831910000,
                "bankName": null,
                "refundReason": "Testing"
            },
            {
                "isPaymentInitiatorOrg": false,
                "paymentId": 885,
                "createdByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "paymentDate": 1635791400000,
                "paymentAmount": 10,
                "paymentStatus": "Processing",
                "paymentMode": "To Funds",
                "paymentType": "Refund",
                "invoiceId": 0,
                "modifiedAt": 1635831695000,
                "bankName": null,
                "refundReason": "Testing"
            },
            {
                "isPaymentInitiatorOrg": false,
                "paymentId": 884,
                "createdByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "paymentDate": 1635791400000,
                "paymentAmount": 10,
                "paymentStatus": "Processing",
                "paymentMode": "To Funds",
                "paymentType": "Refund",
                "invoiceId": 0,
                "modifiedAt": 1635831127000,
                "bankName": null,
                "refundReason": "Testing"
            },
            {
                "isPaymentInitiatorOrg": false,
                "paymentId": 883,
                "createdByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "paymentDate": 1635791400000,
                "paymentAmount": 10,
                "paymentStatus": "Processing",
                "paymentMode": "To Funds",
                "paymentType": "Refund",
                "invoiceId": 0,
                "modifiedAt": 1635830983000,
                "bankName": null,
                "refundReason": "Testing"
            }
        ],
        "totalRecords": 68,
        "filteredRecords": 68
    }
}

Get list of Customer payments​

GET

Get a list of payments by a Customer.

Query parameters
owId
integer		Organization Workspace ID.
status
string		Status type.
Supported values
1Processing
2Paid
3Rejected
4Cancelled
paymentType
string		Payment Type.
Supported values
1As fund
2Against invoice
3Refund
searchField
string		Filter results by search field.
limit
integer		Number of entries returned per page, default: 10.
pageNo
integer		Page number of retrieved data, default: 1.
sortBy
string		Sorts by ascending (+) or descending (-), default: -modifiedAt.
Supported values: paymentId, paymentDate, paymentAmount, organizationName, paymentType, paymentMode, paymentStatus.
Response properties
isPaymentInitiatorOrg
boolean		Indicates whether payment was created by logged-in Organization (true) or not (false).
paymentId
integer		Payment ID.
createdAt
integer		Unix epoch timestamp of invoice payment creation.
createdByUserEmail
string		Created by user email.
createdByUserProfile
string		Created by user profile.
paymentDate
integer		Payment date.
paymentAmount
integer		Payment amount.
paymentStatus
string		Payment status.
Supported values
1Processing
2Paid
3Rejected
4Cancelled
paymentMode
string		Payment mode.
Supported values
1PayPal
2Cheque
3Wire transfer
paymentType
string		Payment type.
Supported values
1As fund
2Against invoice
3Refund
invoiceId
integer		Invoice ID.
transactionId
integer		Transaction ID.
modifiedAt
integer		Unix epoch timestamp of modification date, in milliseconds.
modifiedByUserEmail
string		User email who last modified.
modifiedByUserProfile
string		User profile of who last modified.
bankName
string		Bank name.
refundReason
string		Refund reason.
Response 200
{
    "success": true,
    "data": {
        "data": [
            {
                "isPaymentInitiatorOrg": false,
                "paymentId": 19,
                "createdAt": 1632295016000,
                "createdByUserEmail": "jinesh.p+nonihpcust2@iqm.com",
                "createdByUserProfile": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/JO.svg",
                "paymentDate": 1632076200000,
                "paymentAmount": 10000,
                "paymentStatus": "Rejected",
                "paymentMode": "PayPal",
                "paymentType": "As Fund",
                "invoiceId": 0,
                "transactionId": "T-1234567",
                "modifiedAt": 1637566978000,
                "modifiedByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "modifiedByUserProfile": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/JO.svg",
                "bankName": null,
                "refundReason": null
            },
            {
                "isPaymentInitiatorOrg": false,
                "paymentId": 886,
                "createdAt": 1635831910000,
                "createdByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "createdByUserProfile": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/JO.svg",
                "paymentDate": 1635791400000,
                "paymentAmount": 10,
                "paymentStatus": "Processing",
                "paymentMode": "Check",
                "paymentType": "Refund",
                "invoiceId": 0,
                "transactionId": "123456",
                "modifiedAt": 1635831910000,
                "modifiedByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "modifiedByUserProfile": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/JO.svg",
                "bankName": null,
                "refundReason": "Testing"
            },
            {
                "isPaymentInitiatorOrg": false,
                "paymentId": 885,
                "createdAt": 1635831695000,
                "createdByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "createdByUserProfile": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/JO.svg",
                "paymentDate": 1635791400000,
                "paymentAmount": 10,
                "paymentStatus": "Processing",
                "paymentMode": "To Funds",
                "paymentType": "Refund",
                "invoiceId": 0,
                "transactionId": "123456",
                "modifiedAt": 1635831695000,
                "modifiedByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "modifiedByUserProfile": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/JO.svg",
                "bankName": null,
                "refundReason": "Testing"
            },
            {
                "isPaymentInitiatorOrg": false,
                "paymentId": 884,
                "createdAt": 1635831127000,
                "createdByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "createdByUserProfile": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/JO.svg",
                "paymentDate": 1635791400000,
                "paymentAmount": 10,
                "paymentStatus": "Processing",
                "paymentMode": "To Funds",
                "paymentType": "Refund",
                "invoiceId": 0,
                "transactionId": "123456",
                "modifiedAt": 1635831127000,
                "modifiedByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "modifiedByUserProfile": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/JO.svg",
                "bankName": null,
                "refundReason": "Testing"
            },
            {
                "isPaymentInitiatorOrg": false,
                "paymentId": 883,
                "createdAt": 1635830983000,
                "createdByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "createdByUserProfile": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/JO.svg",
                "paymentDate": 1635791400000,
                "paymentAmount": 10,
                "paymentStatus": "Processing",
                "paymentMode": "To Funds",
                "paymentType": "Refund",
                "invoiceId": 0,
                "transactionId": null,
                "modifiedAt": 1635830983000,
                "modifiedByUserEmail": "jinesh.p+ihpcust@iqm.com",
                "modifiedByUserProfile": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/JO.svg",
                "bankName": null,
                "refundReason": "Testing"
            }
        ],
        "totalRecords": 68,
        "filteredRecords": 68
    }
}

Add payment for Customer​

POST

Add a payment for a Customer. This endpoint also accepts query parameters as multipart/form-data along with image file upload for proof of payment.

Query parameters
owId
integer required		Organization Workspace ID.
paymentAmount
integer required		Payment amount.
paymentDate
string required		Payment date in YYYY-MM-DD format.
paymentMode
integer required		Payment mode type ID.
Supported values
1PayPal
2Cheque
3Wire transfer
transactionId
integer required		Transaction ID.
paymentType
integer required		Payment type ID.
Supported values
1As fund
2Against invoice
3Refund
invoiceId
integer required		Invoice ID (provide only if paymentType is Against Invoice).
Request schema
paymentProof
multipart/form-data optional		Proof of payment image (jpeg/png).
Response properties
success
boolean		Indicates payments successfully added: true.
data
string		Success message.
Request sample
curl -X POST "https://api.example.com/api/v3/fa/customer/payment/add" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-IAA-OW-ID: 200001" \
  -H "Content-Type: multipart/form-data" \
  -F "invoiceId=12345" \
  -F "owId=200001" \
  -F "paymentAmount=1250.50" \
  -F "paymentDate=2025-10-07T12:00:00Z" \
  -F "paymentMode=2" \
  -F "transactionId=TXN-987654321" \
  -F "paymentType=1" \
  -F "paymentProof=@/path/to/payment_receipt.pdf"

Response 200
{
    "success": true,
    "data": "Payment added Successfully."
}

Edit Customer payment​

PUT

Update a payment for a Customer. This endpoint also accepts query parameters as multipart/form-data along with image file upload for proof of payment.

Path parameter
paymentId
integer		Payment ID.
Query parameters
owId
integer required		Organization Workspace ID.
paymentAmount
integer required		Payment amount.
paymentDate
string required		Payment date in YYYY-MM-DD format.
paymentMode
integer required		Payment mode type ID.
Supported values
1PayPal
2Cheque
3Wire transfer
transactionId
integer required		Transaction ID.
paymentType
integer required		Payment type ID.
Supported values
1As fund
2Against invoice
3Refund
invoiceId
integer		Invoice ID (provide only if paymentType is Against Invoice).
refundReason
string		Reason for refund (provide only if paymentType is Refund).
Request schema
paymentProof
multipart/form-data optional		Proof of payment image (jpeg/png).
Response properties
success
boolean		Indicates payments successfully updated: true.
data
string		Success message.
Request sample
curl -X POST "https://api.example.com/api/v3/fa/customer/payment/{paymentId}" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-IAA-OW-ID: 200001" \
  -H "Content-Type: multipart/form-data" \
  -F "invoiceId=12345" \
  -F "owId=200001" \
  -F "paymentAmount=1250.50" \
  -F "paymentDate=2025-10-07T12:00:00Z" \
  -F "paymentMode=2" \
  -F "transactionId=TXN-987654321" \
  -F "paymentType=1" \
  -F "paymentProof=@/path/to/payment_receipt.pdf"

Response 200
{
    "success": true,
    "data": "Payment updated Successfully."
}

Approve payment​

POST

Approve a payment for a Customer.

Path parameter
paymentId
integer		Payment ID.
Request schema
owId
integer		Organization Workspace ID.
actionNote
string		Description of payment status change.
Response properties
success
boolean		Indicates payments successfully approved: true.
data
string		Success message.
Request sample
{
    "owId": 200485,
    "actionNote": "Payment paid partially"
}
{
    "success": true,
    "data": "Payment approved Successfully."
}

Cancel payment​

POST

Cancel a payment for a Customer.

Path parameter
paymentId
integer		Payment ID.
Request schema
owId
integer		Organization Workspace ID.
actionNote
string		Action note.
Response properties
success
boolean		Indicates payments successfully cancelled: true.
data
string		Success message.
Response 200
{
    "success": true,
    "data": "Payment cancelled Successfully."
}

Reject payment​

POST

Reject a payment for a Customer.

Path parameter
paymentId
integer		Payment ID.
Request schema
owId
integer		Organization Workspace ID.
actionNote
string		Action note.
Response properties
success
boolean		Indicates payments successfully rejected: true.
data
string		Success message.
Response 200
{
    "success": true,
    "data": "Payment rejected Successfully."
}

Add payment from Organization app​

POST

Add a payment from a logged-in Organization. This endpoint also accepts query parameters as multipart/form-data along with image file upload for proof of payment.

Query parameters
paymentAmount
integer required		Payment amount.
paymentDate
string required		Payment date in YYYY-MM-DD format.
paymentMode
integer required		Payment mode type ID.
Supported values
1PayPal
2Cheque
3Wire transfer
bankName
string		Required only if paymentMode is Check or Wire Transfer.
Request schema
paymentProof
multipart/form-data optional		Proof of payment image (jpeg/png).
Response properties
success
boolean		Indicates payments successful: true.
data
string		Success message.
Request sample
curl -X POST "https://api.example.com/api/v3/fa/payment/add-fund" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "X-IAA-OW-ID: 200001" \
-H "Content-Type: multipart/form-data" \
-F "paymentAmount=1250.50" \
-F "paymentDate=2025-10-07T12:00:00Z" \
-F "paymentMode=2" \
-F "paymentProof=@/path/to/payment_receipt.pdf"
Response 200
{
    "success": true,
    "data": "Payment Successful."
}

Payment with PayPal​

POST

Make a payment using PayPal gateway.

Request schema
paymentAmount
integer		Payment amount.
Response properties
success
boolean		Indicates payments successful: true.
data
string		PayPal link.
Response 200
{
    "success": true,
    "data": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-3YM2956846765604B"
}

PayPal payment success callback​

GET

Validates a PayPal payment and checks if it has been completed. This is the callback URL that PayPal redirects to after a successful payment approval.

Path parameters
internalToken
string required		Internal token for the payment session.
Query parameters
paymentId
string required		PayPal payment identifier.
PayerID
string required		PayPal payer identifier.
Response properties
success
boolean		Indicates request was successful: true.
Response 200
{
    "success": true
}

PayPal payment cancel callback​

GET

Cancels an in-progress PayPal payment. This is the callback URL that PayPal redirects to when a user cancels the payment flow.

Path parameters
internalToken
string required		Internal token for the payment session.
Response properties
success
boolean		Indicates request was successful: true.
Response 200
{
    "success": true
}

Complete PayPal payment​

GET

Completes the PayPal payment flow and returns a confirmation.

Query parameters
owId
integer required		Customer Organization Workspace ID.
paymentId
integer required		Payment ID.
comment
string required		Comment on payment.
customerRequest
boolean required		Flag for requested by customer.
Response properties
success
boolean		Indicates request was successful: true.
data
string		Confirmation message.
Response 200
{
    "success": true,
    "data": "Comment saved successfully."
}

Initiate refund​

POST

Add a payment for refund to a Customer. This endpoint also accepts query parameters as multipart/form-data along with image file upload for proof of payment.

Query parameters
owId
integer required		Organization Workspace ID.
paymentAmount
integer required		Payment amount.
paymentDate
string required		Payment date in YYYY-MM-DD format.
paymentMode
integer required		Payment mode type ID.
Supported values
1PayPal
2Cheque
3Wire transfer
transactionId
integer		Transaction ID.
refundReason
string required		Reason for refund.
Request schema
paymentProof
multipart/form-data optional		Proof of payment image (jpeg/png).
Response properties
success
boolean		Indicates refund successful: true.
data
string		Success message.
Request sample
curl -X POST "https://api.example.com/api/v3/fa/customer/payment/refund" \
  -H "Authorization Bearer <token>" \
  -H "X-IAA-OW-ID: 200001" \
  -H "Content-Type: multipart/form-data" \
  -F "owId=200001" \
  -F "paymentAmount=1250.50" \
  -F "paymentDate=2025-10-07T12:00:00Z" \
  -F "paymentMode=2" \
  -F "transactionId=TXN-987654321" \
  -F "paymentProof=@/path/to/payment_receipt.pdf"

Approve refund​

POST

Approve a refund for a Customer. This endpoint also accepts query parameters as multipart/form-data along with image file upload for proof of payment.

Path parameter
paymentId
integer		Payment ID.
Query parameters
owId
integer		Organization Workspace ID.
actionNote
string		Description of status change.
Request schema
paymentProof
multipart/form-data		Proof of payment image (jpeg/png).
Response properties
success
boolean		Indicates refund successfully approved: true.
data
string		Success message.
Request sample
curl -X POST "https://api.example.com/api/v3/fa/customer/payment/approve-refund/{paymentId}" \
-H "Authorization Bearer <token>" \
-H "X-IAA-OW-ID: 200001" \
-H "Content-Type: multipart/form-data" \
-F "owId=200001" \
-F "paymentProof=@/path/to/payment_receipt.pdf"
Response 200
{
    "success": true,
    "data": "Refund successful."
}

Email payment receipt​

POST

Send payment receipt to specified email address.

Path parameter
owId
integer		Organization Workspace ID.
paymentId
integer		Payment ID.
Request schema
email
string		Email to send receipt to.
Response properties
success
boolean		Indicates email successfully sent: true.
data
string		Success message.
Request sample
{
    "email": "example@business.com"
}
Response 200
{
    "success": true,
    "data": "Payment receipt e-mail sent successfully."
}

Download payment receipt​

GET

Download a PDF of payment receipt.

Path parameter
paymentId
integer		Payment ID.
Query parameter
owId
integer		Organization Workspace ID.
isCustomerRequest
boolean		Customer app request (default): true.
Organization app request: false.
Request sample
curl -X GET "https://api.iqm.com/api/v3/fa/payment/download-receipt/{paymentId}?owId=200001&isCustomerRequest=true" \ 
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-IAA-OW-ID: 200001"

Add or update payment comment​

PATCH

Add or update a comment on a payment record.

Request schema
owId
integer required		Organization Workspace ID.
paymentId
integer required		Payment ID.
comment
string required		Comment text to add or update.
customerRequest
boolean		Indicates whether this is a customer-initiated request.
Response properties
success
boolean		Indicates request was successful: true.
data
string		Success message.
Response 200
{
    "success": true,
    "data": "Comment saved successfully."
}

Static details lists​

Payment types​

GET

Get a list of payment type IDs.

Payment type IDs
1
As Fund		Payment added into Organization balance.
2
Against Invoice		Payment used to pay invoice.
3
Refund		Payment reversed from platform, deducted from Organization's balance and refunded to Customer Organization.
Response 200
{
    "success": true,
    "data": [
        {
            "name": "as_fund",
            "id": 1,
            "label": "As Fund",
            "order": 1
        },
        {
            "name": "against_invoice",
            "id": 2,
            "label": "Against Invoice",
            "order": 2
        },
        {
            "name": "refund",
            "id": 3,
            "label": "Refund",
            "order": 3
        }
    ]
}

Payment status​

GET

Get a list of payment status IDs.

Properties
1
Processing		Payment in process.
2
Paid		Payment paid.
3
Rejected		Payment rejected.
4
Cancelled		Payment cancelled.
Response 200
{
    "success": true,
    "data": [
        {
            "name": "processing",
            "id": 1,
            "label": "Processing",
            "order": 1
        },
        {
            "name": "paid",
            "id": 2,
            "label": "Paid",
            "order": 2
        },
        {
            "name": "rejected",
            "id": 3,
            "label": "Rejected",
            "order": 3
        },
        {
            "name": "cancelled",
            "id": 4,
            "label": "Cancelled",
            "order": 4
        }
    ]
}

Invoice payment mode types​

GET

Get a list of payment mode type IDs.

Payment mode type IDs
1
PayPal		Payment by PayPal.
2
Check		Payment by check.
3
Wire Transfer		Payment by wire transfer.
Response 200
{
    "success": true,
    "data": [
        {
            "name": "paypal",
            "id": 1,
            "label": "PayPal",
            "order": 1
        },
        {
            "name": "cheque",
            "id": 2,
            "label": "Cheque",
            "order": 2
        },
        {
            "name": "wire_transfer",
            "id": 3,
            "label": "Wire Transfer",
            "order": 3
        }
    ]
}

Invoice status​

GET

Get a list of invoice status type IDs.

Invoice status IDs
1
Pending		Invoice pending.
2
Partially Paid		Invoice partially paid.
3
Unpaid		Invoice not paid.
4
Paid		Invoice paid.
5
Overdue		Invoice payment overdue.
7
Processing		Invoice payment processing.
8
Cancelled		Invoice payment cancelled.
Response 200
{
    "success": true,
    "data": [
        {
            "name": "pending",
            "id": 1,
            "label": "Pending",
            "order": 1
        },
        {
            "name": "partially_paid",
            "id": 2,
            "label": "Partially Paid",
            "order": 2
        },
        {
            "name": "unpaid",
            "id": 3,
            "label": "Unpaid",
            "order": 3
        },
        {
            "name": "paid",
            "id": 4,
            "label": "Paid",
            "order": 4
        },
        {
            "name": "overdue",
            "id": 5,
            "label": "Overdue",
            "order": 5
        },
        {
            "name": "processing",
            "id": 7,
            "label": "Processing",
            "order": 7
        },
        {
            "name": "cancelled",
            "id": 8,
            "label": "Cancelled",
            "order": 8
        }
    ]
}

Invoice payment term​

GET

Get a list of invoice payment term IDs.

Payment term IDs
1
Net 7		Payment expected within 7 days of invoice date.
2
Net 15		Payment expected within 15 days of invoice date.
3
Net 30		Payment expected within 30 days of invoice date.
4
Net 45		Payment expected within 45 days of invoice date.
5
Net 60		Payment expected within 60 days of invoice date.
6
Net 90		Payment expected within 90 days of invoice date.
7
Net 120		Payment expected within 120 days of invoice date.
8
Custom		Payment expected within set days of invoice date.
{
    "success": true,
    "data": [
        {
            "name": "7",
            "id": 1,
            "label": "Net 7",
            "order": 1
        },
        {
            "name": "15",
            "id": 2,
            "label": "Net 15",
            "order": 2
        },
        {
            "name": "30",
            "id": 3,
            "label": "Net 30",
            "order": 3
        },
        {
            "name": "45",
            "id": 4,
            "label": "Net 45",
            "order": 4
        },
        {
            "name": "60",
            "id": 5,
            "label": "Net 60",
            "order": 5
        },
        {
            "name": "90",
            "id": 6,
            "label": "Net 90",
            "order": 6
        },
        {
            "name": "120",
            "id": 7,
            "label": "Net 120",
            "order": 7
        },
        {
            "name": "0",
            "id": 8,
            "label": "Custom",
            "order": 8
        }
    ]
}

PG payment type​

GET

Get a list of PG payment type IDs.

PG payment type IDs
1Publisher payment.
2 Platform payment.
Response 200
{
    "success": true,
    "data": {
        "totalRecords": 2,
        "filteredRecords": 2,
        "pgPaymentTypes": [
            {
                "id": 1,
                "name": "publisher",
                "label": "Publisher",
                "order": 1
            },
            {
                "id": 2,
                "name": "platform",
                "label": "Platform",
                "order": 2
            }
        ]
    }
}
Have a question?
Ask the community
Was this page helpful?