Summary
This area keeps the status of an existing iPaaS.com transaction in step with its Heartland counterpart. When a Heartland order moves from open to closed, or a ticket is completed, the Heartland status is converted to the equivalent iPaaS.com status and written to the transaction that is already linked in iPaaS.com.
It is an update-only area: it never creates an iPaaS.com transaction. The transaction must already exist and be linked by its external id before a status update can be applied. The Add Heartland Sales Order TO iPaaS.com, Add Heartland Invoice TO iPaaS.com, and Add Heartland Ticket TO iPaaS.com areas create the transaction records that this area later keeps in sync.
The other distinctive behavior is preservation. Status is the only value this area actively changes. Every financial and identity value on the transaction — system id, transaction number, type, customer, company, parent, email address, total, subtotal, discount, tax, shipping, and total quantity — is deliberately read back from the existing iPaaS.com record and written again unchanged, so a status update does not disturb the transaction's money or its relationships. The Heartland raw status text and source location are also recorded in custom fields for reference.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the Heartland transaction's external id including its type suffix — for example, 100845_ORDER, 100845_TICKET, or 100845_INVOICE. The suffix is required: without an _ORDER, _INVOICE, or _TICKET suffix the integration cannot determine which Heartland record to retrieve and the transfer fails.
External ID Format
iPaaS.com stores the Heartland transaction identifier with its type suffix as the external-id link between the two systems (for example, 100845_ORDER). Because Heartland reuses numeric identifiers across orders, tickets, and invoices, the suffix is what keeps the external id unique in iPaaS.com. This value is how the integration locates the existing iPaaS.com transaction to update. If no iPaaS.com transaction is linked by that external id, there is nothing for this area to update.
Deleted Record Support
Deleting a transaction is not supported in this direction. The integration does not delete Heartland transactions, and removing or voiding a transaction in Heartland does not delete the linked iPaaS.com Transaction record. A cancelled Heartland transaction is reflected in iPaaS.com as a status change to Cancelled rather than as a deletion. Transactions that should no longer appear in iPaaS.com must be managed directly in iPaaS.com.
Custom Field Support
Heartland transaction custom field values can be read and stored on the iPaaS.com transaction. Add a mapping of type Dynamic Formula whose source reads a named Heartland custom field, and choose the iPaaS.com destination where the value should be stored.
Three custom field destinations ship with the default mappings:
Heartland Order Status: the Heartland transaction's raw status text, stored alongside the translated iPaaS.com status.
Heartland Source Location Id: the Heartland location the transaction originated from.
C5_Custom_Transaction: a template demonstration of the custom-field read pattern. The Heartland custom field name in this mapping is a placeholder and should be replaced with the name of the Heartland custom field you actually want to read, or the mapping removed.
Each destination requires a matching iPaaS.com custom field on the Transaction collection before its value is stored. If the custom field does not exist, the status update still succeeds and the remaining fields are written; only that custom value is not retained.
Heartland tickets and orders require separate custom field group definitions in Heartland even though both arrive in iPaaS.com as Transaction records. A Heartland custom field must exist in Heartland before it is available to mappings.
Mapping Collection Status
Status: Enabled. A conditional filter is applied, described under Mappings — it is a genuine filter, not a disabling switch, so the area is active whenever polling or Manual Sync supplies a qualifying transaction.
Trigger Events: Automatic transfers run on a schedule through transaction polling. Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so status changes arrive through polling rather than instant push notifications. Polling does not run until the subscription is configured and enabled. The polling filter determines which transaction type is retrieved; when no filter is supplied, transaction polling defaults to Heartland orders. An individual transaction can also be updated at any time from the Manual Sync page by entering its suffixed external id.
Duplicate or Conflicting Mappings
Several other areas operate on Transaction records and should be reviewed together with this one.
Same inbound direction (Heartland to iPaaS.com): Add Heartland Sales Order TO iPaaS.com, Add Heartland Invoice TO iPaaS.com, Add Heartland Ticket TO iPaaS.com, and Add Heartland Sales Order Deposit TO iPaaS.com. These create the transaction records that this area later updates. They do not compete with it, because this area only ever updates a transaction that one of them has already created and linked.
Opposite direction (iPaaS.com to Heartland): Add/Update Heartland Sales Order FROM iPaaS.com, Add Heartland Invoice FROM iPaaS.com, Update Heartland Invoice FROM iPaaS.com, and Add Heartland Ticket FROM iPaaS.com.
Before running the inbound and outbound directions together, review your mapping filters and decide explicitly which system is the source of truth for transaction status. If both directions are active with the default mappings, a status change can propagate back and forth between the systems. Running all transaction areas bi-directionally without such a plan is not recommended.
Collision Handling
This integration does not use iPaaS.com collision handling for transactions. Which iPaaS.com transaction is updated is determined solely by the suffixed external id link; there is no collision recovery step to configure.
Supported Child Collections
None. This is a standalone area with no dependent child collections. It updates the transaction header only. Line items, payments, addresses, taxes, notes, and tracking are handled by the separate Add-direction transaction areas.
System Caveats
Heartland Caveats
Heartland reuses numeric identifiers across orders, tickets, and invoices. The integration appends a type suffix to keep external ids unique in iPaaS.com, so always reference the suffixed external id rather than the raw Heartland number when identifying a transaction to update.
Deposit records created for compatibility carry a "-D" marker on their identifiers and are intentionally excluded by this area's filter.
Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so status changes are picked up by polling. Expect a delay between a status change in Heartland and its appearance in iPaaS.com, bounded by the polling schedule.
A Heartland custom field must be created in Heartland before it is available to mappings, and tickets and orders require separate custom field group definitions.
iPaaS.com Caveats
The transaction must already exist and be linked in iPaaS.com. This area does not create transactions; if no linked transaction is found, there is nothing to update.
iPaaS.com requires a system id greater than zero, a transaction number that is unique across iPaaS.com transactions, a transaction type, and a status on every transaction.
iPaaS.com requires every transaction to be tied to a customer or company: at least one of the customer id, company id, or email address must be present, or the update is rejected.
The iPaaS.com Status field accepts a fixed set of values. The status translation maps Heartland statuses onto those values.
Custom values are stored only when a matching custom field exists on the Transaction collection.
Integration-Specific Caveats
Status is the only value this area changes. Every other mapped value is read from the existing iPaaS.com transaction and written back unchanged, by design.
Because every preserved value is sourced from the iPaaS.com record rather than from Heartland, a discrepancy between the two systems' financial totals is not corrected by a status update. This area is not a means of re-syncing transaction amounts.
Pending Heartland transactions and deposit records are skipped entirely and are never updated through this area.
Setup Requirements
Heartland Configuration
Confirm the transactions you expect to update exist in Heartland and carry the status values you intend to propagate.
Create any Heartland custom fields you intend to read before configuring the mappings, and create them for the correct record type — tickets and orders require separate custom field group definitions.
iPaaS.com Configuration
Run the relevant Add-direction transaction areas first, so the transactions this area updates exist and are linked by their suffixed external ids.
Review the Transaction Status translation and add a row for any Heartland status your business uses that is not already covered, so it resolves to a valid iPaaS.com status.
Create the Heartland Order Status and Heartland Source Location Id custom fields on the Transaction collection if you want those Heartland values retained.
Replace the placeholder Heartland custom field name in the C5_Custom_Transaction mapping with a real Heartland custom field name, or remove the mapping.
Enable the subscription so transaction polling can run.
Authentication & Security
Heartland uses OAuth 2.0 to obtain an access token, which authorizes the Heartland API requests made during a transfer. Credentials are configured on the Heartland subscription — see the Heartland Installation Instructions.
Integration Flow
Scheduled polling:
On its polling schedule, the integration requests the current set of transactions from Heartland. The polling filter determines which transaction type is retrieved; with no filter supplied, orders are polled.
For each transaction returned, the full Heartland transaction record is retrieved.
Before the transaction itself is dispatched, the integration resolves its prerequisites in this order. If the transaction names a Heartland customer that is not yet linked in iPaaS.com, that customer is retrieved and transferred first; if the customer transfer fails, the transaction transfer is stopped with an error. Next, for each payment on the transaction, an unrecognized payment type is retrieved and transferred as a payment method, and a gift card payment causes the gift card to be retrieved and updated. Finally, on Ticket transactions only, any line item tied to a gift card causes that gift card to be retrieved and transferred.
The transaction is then dispatched to iPaaS.com, where the mapping filter is evaluated. Deposit records and pending transactions are skipped.
For a qualifying transaction, the integration locates the linked iPaaS.com transaction by its suffixed external id, converts the Heartland status through the translation, and updates the status while writing every other mapped value back from the existing iPaaS.com record.
Manual Sync:
A Heartland transaction external id, including its _ORDER, _INVOICE, or _TICKET suffix, is entered on the iPaaS.com Manual Sync page.
The integration retrieves that single transaction from Heartland. If the id has no recognized type suffix, the transfer fails before the record is retrieved.
The same prerequisite resolution and the same filter and update path described above are applied, so the resulting iPaaS.com record is identical to the one produced by polling.
Mappings
Update Heartland Transaction Status TO iPaaS.com
Mapping Filter
!External_Id.Contains("-D")
&& Status != "pending"Both conditions must be true for a Heartland transaction to be processed by this area:
The transaction's external id must not contain "-D". Deposit records created by the integration for compatibility carry a "-D" marker on their external id, so this condition excludes deposit transactions from status updates.
The Heartland status must not be "pending". Pending transactions are skipped so that only settled statuses are propagated to iPaaS.com.
A Heartland transaction that is a deposit record, or that is still pending, is skipped without being updated. No error is raised for a skipped record; it simply does not reach the mapping.
Description: Updates the status of the iPaaS.com transaction already linked to this Heartland transaction, matched by the suffixed Heartland external id. Status is the only value changed; all remaining mappings read the existing iPaaS.com value and write it back so that nothing else on the record is altered. This area never creates a transaction.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Lookup Translation | Status | Status | Required. Converts the Heartland transaction status to the corresponding iPaaS.com status through the Transaction Status translation. This is the one field the area actively updates. iPaaS.com requires a status on every transaction. The translation value pairs are listed below this table. |
Dynamic Formula |
| SystemId | Required. Reuses the system id already stored on the iPaaS.com transaction, keeping the update pointed at the same record. iPaaS.com requires a system id greater than zero. |
Dynamic Formula |
| TransactionNumber | Required. Reuses the transaction number already stored on the iPaaS.com transaction, keeping the record's unique identifier intact. iPaaS.com requires a transaction number and it must be unique. |
Dynamic Formula |
| Type | Required. Reuses the transaction type already stored on the iPaaS.com transaction (such as Order, Invoice, or Ticket), so the status update does not change the record's type. |
Dynamic Formula |
| CustomerId | Required as part of a set. Reuses the customer id already stored on the iPaaS.com transaction, so the update does not change which customer the transaction is tied to. iPaaS.com requires at least one of customer id, company id, or email address on every transaction. |
Dynamic Formula |
| CompanyId | Required as part of a set. Reuses the company id already stored on the iPaaS.com transaction, so the update does not change which company the transaction is tied to. One of the three values that satisfy the customer-or-company requirement. |
Dynamic Formula |
| EmailAddress | Required as part of a set. Reuses the email address already stored on the iPaaS.com transaction. One of the three values that satisfy the customer-or-company requirement. |
Dynamic Formula |
| ParentId | Optional. Reuses the parent transaction id already stored on the iPaaS.com transaction, so an existing parent-child relationship — for example a deposit or invoice linked to its order — is preserved through the status update. |
Dynamic Formula |
| Total | Optional. Reuses the total already stored on the iPaaS.com transaction so the status update leaves the record's monetary totals unchanged. |
Dynamic Formula |
| Subtotal | Optional. Reuses the subtotal already stored on the iPaaS.com transaction so the status update leaves the record's monetary totals unchanged. |
Dynamic Formula |
| DiscountAmount | Optional. Reuses the discount amount already stored on the iPaaS.com transaction so the status update leaves the record's monetary totals unchanged. |
Dynamic Formula |
| TaxAmount | Optional. Reuses the tax amount already stored on the iPaaS.com transaction so the status update leaves the record's monetary totals unchanged. |
Dynamic Formula |
| ShippingAmount | Optional. Reuses the shipping amount already stored on the iPaaS.com transaction so the status update leaves the record's monetary totals unchanged. |
Dynamic Formula |
| TotalQty | Optional. Reuses the total quantity already stored on the iPaaS.com transaction so the status update leaves the record's line quantities unchanged. |
Field | Status | Heartland Order Status (custom field) | Optional. Stores the Heartland transaction's raw status text, giving a record of the original Heartland status alongside the translated iPaaS.com status. Requires a custom field of this name on the Transaction collection before the value is stored. |
Field | SourceLocationId | Heartland Source Location Id (custom field) | Optional. Stores the Heartland source location id, recording which Heartland location the transaction originated from. Requires a custom field of this name on the Transaction collection before the value is stored. |
Dynamic Formula |
| C5_Custom_Transaction (custom field) | Optional. Reads a named value from the Heartland transaction's custom fields and stores it in an iPaaS.com custom field, demonstrating the custom-field read pattern. The Heartland custom field name shown is a placeholder: replace it with the name of the Heartland custom field you want to read, and point the mapping at the iPaaS.com custom field where the value should be stored. Both the Heartland custom field and the iPaaS.com destination custom field must exist first. |
The Transaction Status translation applies the following value pairs:
Heartland Status | iPaaS.com Status |
pending | Pending |
canceled | Cancelled |
open | Pending |
closed | Complete |
complete | Complete |
Add a translation row for any Heartland status your business uses that is not listed above, so that it resolves to a valid iPaaS.com status. Note that the mapping filter already excludes transactions whose Heartland status is "pending", so that first pair does not apply during a normal transfer through this area.
Unmapped Field Overwrite Risk
When iPaaS.com updates an existing Transaction record, the full record is replaced: any writable top-level field that is neither mapped nor preserved is cleared on each update. This area is deliberately designed to avoid that outcome, which is why every financial and identity field appears in the table above with its existing iPaaS.com value read back and rewritten.
The top-level writable fields it does not map or preserve are the transaction created and updated timestamps. If your integration relies on those being retained, add mappings that preserve them before running status updates. More generally, review the Transaction fields your integration depends on and confirm each one is either mapped or preserved before enabling this area.
Error Handling
Transaction not found in iPaaS.com: this area only updates. If no iPaaS.com transaction is linked by the suffixed Heartland external id, there is no record to update. Run the relevant Add-direction transaction area first so the transaction exists and is linked.
Missing or invalid type suffix: a Manual Sync id must include an _ORDER, _INVOICE, or _TICKET suffix so the integration can determine which Heartland record to retrieve. Without one, the transfer fails before the record is fetched. Re-enter the id with the correct suffix.
Transaction not found in Heartland: when a Manual Sync is run for an external id that does not exist in Heartland, or the record cannot be retrieved, the transfer fails and no iPaaS.com record is updated. Confirm the id is correct and the transaction is still present in Heartland.
Unmapped Heartland status: when a Heartland status has no row in the Transaction Status translation, it does not resolve to a valid iPaaS.com status and the update is rejected, because iPaaS.com requires a status on every transaction. Add the missing translation row and re-transfer.
Missing customer, company, and email address: iPaaS.com requires at least one of these on every transaction. If the existing iPaaS.com record carries none of the three, the update is rejected. Correct the transaction in iPaaS.com, then re-transfer.
Prerequisite customer could not be created: if the transaction names a Heartland customer that is not yet linked in iPaaS.com and that customer cannot be transferred, the transaction transfer is stopped with an error and no status update is applied. Resolve the customer transfer, then re-transfer the transaction.
Custom value not stored: when a destination custom field has not been created on the Transaction collection, the status update still succeeds and the remaining fields are written; only that custom value is not retained. Create the custom field and re-transfer to populate it.
Heartland API unavailable: if the Heartland API is temporarily unavailable when a transfer is triggered, the transfer fails. The error appears in the iPaaS.com Dashboard error logs, and the record can be retried through a new polling cycle or Manual Sync.
Testing & Validation
Test Scenarios
Status update applied — take a Heartland order already linked in iPaaS.com, change its Heartland status from open to closed, transfer it, and confirm the iPaaS.com transaction status changes from Pending to Complete.
No transaction created — pick a Heartland transaction that has never been transferred, run it through this area, and confirm no new iPaaS.com transaction is created.
Financial values preserved — note the total, subtotal, discount, tax, shipping, and total quantity on a linked iPaaS.com transaction, run a status update, and confirm every one of them is unchanged afterwards.
Identity values preserved — confirm the transaction number, type, customer, company, email address, and parent link are unchanged after a status update.
Cancelled status — set a Heartland transaction to canceled, transfer it, and confirm the iPaaS.com status becomes Cancelled rather than the record being deleted.
Pending skipped — leave a Heartland transaction in pending status, run a transfer, and confirm the iPaaS.com transaction is not updated and no error is raised.
Deposit skipped — run a transfer for a deposit record and confirm it is skipped by the filter without being updated.
Unmapped status — introduce a Heartland status with no translation row, transfer it, confirm the update is rejected, then add the translation row and confirm the retry succeeds.
Custom fields populated — with the Heartland Order Status and Heartland Source Location Id custom fields created on the Transaction collection, run a status update and confirm both hold the expected Heartland values.
Custom field absent — remove one of those custom fields, run a status update, and confirm the status still updates with the remaining fields written and no error raised for the missing custom value.
Manual Sync by suffixed id — enter a known Heartland external id with its type suffix on the Manual Sync page and confirm that specific transaction's status updates.
Each transaction type — repeat the basic status update for an order, a ticket, and an invoice, confirming the correct record is matched in each case by its suffixed external id.
Polling — with the subscription enabled, change a Heartland transaction status and confirm the iPaaS.com transaction reflects it on the next polling cycle without manual intervention.
Validation Checklist
Every transaction targeted for a status update already exists in iPaaS.com and is linked by its suffixed external id.
The Transaction Status translation covers every Heartland status your business uses.
The iPaaS.com status after a transfer matches the expected translation of the Heartland status.
Financial totals, quantities, transaction number, type, customer, company, email address, and parent link are all unchanged after a status update.
Deposit records and pending transactions are skipped and never updated.
The Heartland Order Status and Heartland Source Location Id custom fields exist on the Transaction collection and hold the expected values.
The C5_Custom_Transaction mapping either names a real Heartland custom field or has been removed.
The created and updated timestamps behave as your integration expects, since they are not preserved by the default mappings.
Polling and Manual Sync produce the same resulting record for the same transaction.
Additional Notes
This is an update-only area. It has no create path at all, so a transaction that has never been transferred to iPaaS.com cannot be brought in through it. Sequence the Add-direction transaction areas ahead of it.
Heartland is the source of truth for transaction status. Editing the status directly in iPaaS.com will be overwritten on the next status transfer for that transaction.
Because every value other than status is read back from the existing iPaaS.com record, this area cannot be used to repair financial totals that have drifted between the two systems. Re-transfer through the appropriate Add-direction area instead.
Because status changes arrive by polling rather than instant webhooks, allow for the polling interval when validating a change made in Heartland.
Related Documents
Setup & Reference