Summary
Completed Heartland invoice transactions are transferred into iPaaS.com as Transaction records of type Invoice. Along with the transaction header, the integration transfers the invoice's item lines, addresses, and payments through three child mapping collections, and it records several Heartland-specific values — the raw Heartland order status, the source location, and the station — on iPaaS.com custom fields.
This collection handles invoices only. Heartland sales orders, sales order deposits, and tickets are each handled by their own inbound collection so that the different Heartland transaction types can be transferred and filtered independently, even though all of them write to the same iPaaS.com Transaction collection.
iPaaS.com requires a unique transaction number on every Transaction record. Because Heartland auto-increments order, ticket, and invoice numbers separately, the same numeric value can appear on more than one transaction type. To keep the numbers unique, the template maps the Heartland external identifier — which carries an _INVOICE suffix — to the iPaaS.com transaction number. If a transaction with that transaction number already exists in iPaaS.com, the transfer updates that record rather than creating a second one.
This document covers the Heartland → iPaaS.com direction. Separate collections write invoices in the opposite direction, from iPaaS.com into Heartland; they are a different flow with different trigger semantics and are listed under Duplicate or Conflicting Mappings.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the Heartland transaction ID of the invoice in the Heartland input field. That single invoice is then transferred along with its item lines, addresses, and payments.
External ID Format
After a successful transfer, iPaaS.com records the invoice's external-id link in the {invoice_number}_INVOICE format, where {invoice_number} is the Heartland invoice number. The _INVOICE suffix keeps the invoice's transaction number distinct from Heartland order and ticket numbers that may share the same numeric value; Heartland applies the equivalent _ORDER and _TICKET suffixes to those types.
Subsequent transfers of the same invoice match on that transaction number and update the existing iPaaS.com Transaction record rather than creating a duplicate. Whether an incoming invoice is created or updated is determined by whether that transaction number is already present in iPaaS.com, not by which event triggered the transfer.
Deleted Record Support
Deleting a Heartland invoice is not supported by this integration. The integration creates and updates iPaaS.com Transaction records only — removing or voiding an invoice in Heartland does not delete or deactivate the linked iPaaS.com Transaction record. Invoices that should no longer appear must be managed directly in iPaaS.com.
One indirect deletion path does exist and is worth knowing about. When the ParentId mapping links an invoice to its originating Heartland sales order, the invoice becomes a child of that order's iPaaS.com Transaction. Deleting the order in iPaaS.com then also deletes the linked invoice. Remove the ParentId mapping if you do not want the invoice deleted when its order is deleted.
Custom Field Support
This collection stores fixed Heartland values on iPaaS.com custom fields at both the header and the child level:
Heartland Order Status: the raw Heartland transaction status, preserved alongside the translated iPaaS.com Status.
Heartland Source Location Id: the Heartland source location identifier for the invoice.
Heartland Station Id: the Heartland station identifier for the invoice.
Transaction Created By: the static value "Heartland", marking Heartland as the system that originated the invoice. This origin marker is what the outbound filter reads to avoid transferring iPaaS.com-created transactions back into iPaaS.com.
Heartland Invoice Order Line Id, Heartland Ship From Location Id, and Line Created By: stored per line by the invoice line child collection.
Heartland Payment Applied As Deposit and Heartland Payment Type: stored per payment by the invoice payment child collection.
Each requires a matching iPaaS.com subscription custom field on the relevant collection — Transaction, Transaction Line, or Transaction Payment — before its value is stored. If the custom field does not exist, the invoice still transfers and the remaining fields are written; only that custom value is not retained.
The collection can also read arbitrary Heartland transaction custom field values. Add a mapping of type Dynamic Formula whose source calls await GetValueFromCustomField(Custom, "[Heartland custom field name]"); and choose any iPaaS.com destination. At transfer time the integration returns the value of the named Heartland custom field. A Heartland custom field must be created in Heartland before it is visible on the Heartland website and available to mappings.
Mapping Collection Status
Status: Enabled. The parent collection's mapping filter transfers an invoice only when it meets the invoice-and-complete condition described under Mappings.
Trigger Events: The integration registers transaction created, updated, and polling events. In practice automatic transfers run on a schedule through polling: Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so invoices arrive through polling rather than instant push notifications. Polling does not run until the subscription is configured and enabled. Individual invoices can also be transferred at any time from the iPaaS.com Manual Sync page. The three child collections have no trigger of their own; they run only as part of a parent invoice transfer.
Duplicate or Conflicting Mappings
Several other mapping collections operate on iPaaS.com Transaction records. They fall into three groups.
Other Heartland transaction types, same direction. Add Heartland Sales Order TO iPaaS.com, Add Heartland Sales Order Deposit TO iPaaS.com, and Add Heartland Ticket TO iPaaS.com transfer the other Heartland transaction types inbound to the same iPaaS.com Transaction collection. Update Heartland Transaction Status TO iPaaS.com updates the status of transactions already linked to iPaaS.com. These do not conflict with this collection because each filters to its own Heartland transaction type, and the _INVOICE, _ORDER, and _TICKET external-id suffixes keep their transaction numbers from colliding.
The opposite direction — writing invoices into Heartland. Two distinct outbound flows create and update Heartland invoices from iPaaS.com data, and neither is the reverse of this collection:
Add Heartland Invoice FROM iPaaS.com (Invoice): creates a new Heartland invoice directly from an iPaaS.com transaction, where the iPaaS.com transaction is linked solely to the invoice and not to a separate sales order.
Update Heartland Invoice FROM iPaaS.com (Order Complete): creates the Heartland invoice as a consequence of a linked iPaaS.com sales order being completed, so the iPaaS.com transaction is linked to both an order and an invoice.
Those two flows have their own child collections for line items, payments, and tracking numbers. Do not treat them as counterparts to the collections documented here: the mappings, the trigger, and the record-matching behavior all differ.
Child-level overlap. Other Transaction Line, Transaction Address, and Transaction Payment collections exist for the other Heartland transaction types — for example Add Heartland Sales Order Address TO iPaaS.com and Add Heartland Sales Order Payment TO iPaaS.com. Each rides its own parent transaction and processes only that parent's children, so they do not compete with the invoice children.
Important: Template mapping collections are provided for every transaction type in both directions, but running them all bi-directionally is not recommended. Before running the inbound and outbound directions together, review your mapping collection filters and clearly define which system is the source of truth. The Transaction Created By custom field and the parent filter exist specifically so that invoices created by iPaaS.com are not transferred back into iPaaS.com; keep them in place when both directions are active.
Collision Handling
This integration does not use iPaaS.com collision handling for invoices. Whether an incoming invoice is created or updated is determined solely by whether its transaction number is already present in iPaaS.com; there is no collision recovery step to configure.
Supported Child Collections
The parent Add Heartland Invoice TO iPaaS.com collection has three child collections. None of them runs independently, and none has its own schedule, webhook, or Manual Sync entry:
Add Heartland Invoice Line TO iPaaS.com: transfers the invoice's item lines. Only Heartland transaction lines of the item type are transferred; tax and shipping lines are read into the parent's header totals instead.
Add Heartland Invoice Address TO iPaaS.com: transfers the invoice's billing and shipping addresses.
Add Heartland Invoice Payment TO iPaaS.com: transfers the invoice's payments.
System Caveats
Heartland Caveats
Transaction numbering: By default Heartland auto-increments order, ticket, and invoice numbers, and the same numeric value can appear across different types. Map the Heartland external identifier, which includes the _INVOICE suffix, to the iPaaS.com transaction number to keep invoice numbers unique. Mapping the human-friendly Heartland public identifier instead is possible but risks numeric overlap between transaction types, and is only advisable when a single Heartland transaction type is transferred.
Tax and shipping are line items: On a Heartland invoice, sales tax and shipping are recorded as separate line items rather than as header totals. The template reads the amount from the first matching tax or shipping line into the iPaaS.com header TaxAmount and ShippingAmount fields. Those lines are not created as iPaaS.com transaction lines.
Order-to-invoice link: When the invoice's originating order is already linked to an iPaaS.com transaction, the template links the invoice to that order as a child. Deleting the order in iPaaS.com then also deletes the linked invoice.
Order line identifier: When an invoice is created from a Heartland sales order, the Heartland order line identifier accompanies each line. The line child collection stores that identifier on a custom field so it remains available downstream.
Custom field visibility: A Heartland custom field must be created in Heartland before it is visible on the Heartland website and available to mappings.
Polling delay: Because Heartland does not deliver instant push notifications to iPaaS.com, expect a delay between an invoice being completed in Heartland and its arrival in iPaaS.com, bounded by the polling schedule.
iPaaS.com Caveats
Transaction number required and unique: iPaaS.com requires a transaction number on every Transaction record, and it must be unique across iPaaS.com transactions.
Required header values: Every iPaaS.com transaction requires a system id, transaction number, type, and status, plus at least one of a customer, company, or email address. If none of the customer, company, or email address is supplied, the request is rejected. This collection supplies all of these.
System id is not updatable: iPaaS.com accepts the system id when the Transaction record is created and ignores it on update. The SystemId mapping therefore has no effect on an already-linked invoice, and a transaction cannot be moved between subscriptions by re-transferring it.
Payment method name is not updatable: when the integration auto-transfers a Heartland payment method as a prerequisite, iPaaS.com accepts the method name on create only and ignores an incoming name on update. Renaming a payment method in Heartland does not rename the already-linked iPaaS.com Payment Method record, and the payment Method value on invoices will continue to resolve to the original name.
Line status and type required: every iPaaS.com transaction line requires a status and a type. The line child collection supplies both as static values.
SKU resolution: the SKU on a product line should resolve to an existing iPaaS.com product or variant so the line is tied to the correct catalog item.
Payment method required: iPaaS.com requires a method on every payment, and it must match the name of a payment method configured in iPaaS.com.
Gift card requirement: when a payment's method is a gift card method, iPaaS.com requires a gift card id on that payment. The payment child collection supplies it through the MethodInfo mapping.
Custom field prerequisites: every custom field mapped by these collections must already exist on the corresponding iPaaS.com collection before the mapped value is stored.
Integration-Specific Caveats
Products are not auto-transferred. Unlike the customer, payment method, and gift card prerequisites described under Integration Flow, no product prerequisite runs in this direction. The SKU on an invoice line will only resolve if the product or variant already exists in iPaaS.com, so keep your Heartland product collections running ahead of invoice transfers.
Gift cards on line items are a ticket-only prerequisite. The gift-card-from-line-items prerequisite applies only to Heartland transactions of type Ticket. It does not run for invoices; on the invoice flow, gift cards are resolved only from payments.
Updates replace the record. Re-transferring an invoice that already exists in iPaaS.com replaces the Transaction header and its lines. See Unmapped Field Overwrite Risk under Mappings before re-transferring.
Incomplete invoices are simply skipped. The parent filter passes over records that do not qualify without raising an error, so a skipped invoice produces no entry in the error log.
Setup Requirements
Heartland Configuration
Ensure invoices reach the complete status in Heartland; only completed invoices are transferred.
Create any Heartland custom fields you intend to map before configuring the mappings, so they are available for selection.
Keep the Heartland payment methods you use on invoices available, so the payment method prerequisite can resolve or transfer them.
For gift card payments, ensure the gift card number is the last word of the Heartland payment description — that is where the integration reads it from.
iPaaS.com Configuration
Create the custom fields listed under Custom Field Support on the Transaction, Transaction Line, and Transaction Payment collections if you want those Heartland values retained.
Confirm a payment method named "Gift Card_Heartland" exists in iPaaS.com, so the payment Method fallback resolves to a real method rather than failing.
Transfer your Heartland products to iPaaS.com before transferring invoices, so invoice line SKUs resolve to existing products or variants.
Confirm the Transaction Status lookup translation covers every Heartland status you expect. A Heartland status that is not listed is passed through unchanged and may not be a valid iPaaS.com status.
Decide whether you want the ParentId order-to-invoice link before the first transfer, since it also governs cascade deletion.
Enable the subscription so 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
Prerequisites, run before the invoice itself:
Before an invoice is sent to iPaaS.com, the integration resolves the records the invoice depends on. These run automatically — subscribers do not pre-sync them by hand — and they run in this order:
Customer. If the invoice carries a Heartland customer, the integration checks whether that customer is already linked to an iPaaS.com customer. If it is already linked, nothing further happens. If it is not linked, the integration retrieves the Heartland customer and transfers it through the Customer collection first. If that customer transfer reports errors, the invoice transfer is stopped and the invoice is not created in iPaaS.com. Resolve the customer error and re-transfer the invoice.
Payment methods. For each payment on the invoice that carries a Heartland payment method, the integration checks whether a linked iPaaS.com payment method name resolves. If one does, nothing further happens. If none resolves, the integration retrieves the Heartland payment method and transfers it through the Payment Method collection so the payment can reference it.
Gift cards on payments. For each payment whose Heartland payment type indicates a gift card, the integration reads the gift card number from the last word of the payment description, retrieves that gift card from Heartland, and transfers it through the Gift Card collection.
The gift-card-from-line-items prerequisite that exists elsewhere in the integration is gated on the transaction being a Heartland Ticket, so it does not run on the invoice flow.
Scheduled polling:
On its polling schedule, the integration requests the Heartland transactions changed within the configured search window.
Each transaction is evaluated against the parent mapping filter. Only records that are invoices and are complete continue; everything else is passed over.
The prerequisites above are resolved for each qualifying invoice.
The invoice header is dispatched to iPaaS.com, where a Transaction of type Invoice is created if the transaction number is not yet present, or the existing record is updated if it is.
The invoice's item lines, addresses, and payments are dispatched through the three child collections under that transaction.
Manual Sync:
A Heartland transaction ID for an invoice is entered on the iPaaS.com Manual Sync page.
The integration retrieves that single invoice from Heartland.
The invoice is evaluated against the same parent filter, the same prerequisites are resolved, and the invoice and its children are dispatched through the same create-or-update path.
Both paths converge on the same mapping logic, so an invoice's resulting iPaaS.com record is identical regardless of how the transfer was triggered.
Mappings
Add Heartland Invoice TO iPaaS.com
Mapping Filter
var source = await GetValueFromCustomField(Custom, "Transaction Source");
if (source=="iPaaS.com" || External_Id.EndsWith("-D")) {return false;}
else if( External_Id.Contains("_INVOICE") && Status == "complete")
{return true;}
return false;The filter reads the Heartland transaction's Transaction Source custom field, then evaluates the record against three branches:
Skipped when the record originated in iPaaS.com or is a deposit. If the Transaction Source custom field is "iPaaS.com", or the external identifier ends with -D, the record is skipped. The first condition prevents a feedback loop in which the two systems repeatedly update the same record; the second excludes deposit transactions, which are not completed invoices and are handled by their own collection.
Transferred when the record is a complete invoice. Otherwise, if the external identifier contains _INVOICE and the Heartland status is exactly "complete", the record is transferred.
Skipped in every other case. Any record reaching the final branch — an order, a ticket, or an invoice that has not yet reached the complete status — is skipped.
The filter does not raise an error and throws no message. Records that do not qualify are passed over silently, so a skipped invoice produces no entry in the error log. An invoice that is not yet complete is skipped until it reaches the complete status, at which point a later polling cycle picks it up.
Description: Creates or updates the iPaaS.com Transaction record of type Invoice from the completed Heartland invoice, matched by the transaction number carried in the Heartland external identifier. This is the parent of the invoice line, address, and payment child collections.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| SystemId | Required. Supplies the iPaaS.com system (subscription) identifier that the transaction belongs to. iPaaS.com requires a system id on every transaction. The value is provided automatically by the integration; leave this mapping in place. iPaaS.com accepts the system id on create only and ignores it on update. |
Dynamic Formula |
| TransactionNumber | Required. Sets the iPaaS.com transaction number, which must be unique across iPaaS.com transactions. The template maps the Heartland external identifier, producing the number in the {invoice_number}_INVOICE format. The suffix keeps the invoice number distinct from Heartland order and ticket numbers that may share the same numeric value. The commented alternative points the mapping at the Heartland public identifier to use the plain invoice number instead; that is only advisable when a single Heartland transaction type is transferred, because it does not carry the suffix that prevents numeric overlap. |
Static | "Invoice" | Type | Required. Classifies every record transferred by this collection as an invoice. iPaaS.com requires a transaction type, and "Invoice" is one of its valid values. Leave this value in place for the invoice workflow. |
Lookup Translation | Transaction Status translation, applied to the Heartland Status | Status | Required. Converts the Heartland transaction status into the corresponding iPaaS.com transaction status. The translation pairs canceled to Cancelled, open and pending to Pending, and closed and complete to Complete. A Heartland status that is not listed is passed through unchanged; add a pair for any additional Heartland status you need to map. |
Dynamic Formula |
| CustomerId | Required. Looks up the linked iPaaS.com customer for the invoice using the Heartland customer identifier, and stores it on the transaction. iPaaS.com requires at least one of a customer, company, or email address on every transaction; this collection supplies both this and the email address. If the Heartland customer is not yet linked, the customer prerequisite transfers it before the invoice is sent; if it still cannot be resolved, the email address mapping alone allows the transaction to be created. |
Dynamic Formula |
| EmailAddress | Required. Reads the customer email address from the Heartland customer information on the invoice. Together with the CustomerId mapping this satisfies the iPaaS.com requirement for at least one of a customer, company, or email address. |
Dynamic Formula |
| ParentId | Optional. Looks up the invoice's originating Heartland sales order among the linked iPaaS.com transactions and, when a match is found, sets it as the invoice's parent, creating a parent/child relationship between the order and the invoice. Because the invoice becomes a child of the order, deleting the order in iPaaS.com also deletes the linked invoice; remove this mapping if you do not want that cascade. |
Field | OriginalSubtotal | Subtotal | Recommended. Stores the invoice's subtotal — the line total before tax and shipping — so the invoice's financial totals are complete in iPaaS.com. |
Field | Total | Total | Recommended. Stores the invoice's grand total: subtotal plus tax and shipping, less discounts. |
Dynamic Formula |
| TaxAmount | Recommended. On a Heartland invoice, sales tax is stored as a separate line item rather than as a header total. This searches the invoice's transaction lines for the first tax line and returns its amount when that amount is greater than zero; otherwise it returns zero. |
Dynamic Formula |
| ShippingAmount | Recommended. On a Heartland invoice, shipping is stored as a separate line item rather than as a header total. This searches the invoice's transaction lines for the first shipping line and returns its amount when that amount is greater than zero; otherwise it returns zero. |
Field | TotalDiscounts | DiscountAmount | Recommended. Stores the invoice's total discount amount so the invoice's financial totals are complete in iPaaS.com. |
Field | TotalItemQty | TotalQty | Recommended. Stores the total quantity of items on the invoice. |
Field | Status | Heartland Order Status (custom field) | Optional. Stores the raw Heartland transaction status, preserving the original Heartland value 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 identifier for the invoice. Requires a custom field of this name on the Transaction collection before the value is stored. |
Field | StationId | Heartland Station Id (custom field) | Optional. Stores the Heartland station identifier for the invoice. Requires a custom field of this name on the Transaction collection before the value is stored. |
Static | "Heartland" | Transaction Created By (custom field) | Optional. Marks Heartland as the system that originated the invoice. This origin marker is what the outbound filter reads to avoid transferring iPaaS.com-created transactions back into iPaaS.com. 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. This is the custom-field formula pattern for the Transaction collection, shipped with a placeholder name — replace "My Sales Order List Custom Field" with the Heartland custom field you want to read, and point the mapping at the iPaaS.com custom field where the value should be stored. The named Heartland custom field must exist in Heartland, and the destination custom field must exist on the Transaction collection. |
Add Heartland Invoice Line TO iPaaS.com
This collection is a child of Add Heartland Invoice TO iPaaS.com. It does not run on its own and has no schedule, webhook, or Manual Sync entry of its own; it runs whenever the parent transfers an invoice, creating the invoice's item lines as iPaaS.com Transaction Lines under the transaction the parent created or updated.
Mapping Filter
Type=="ItemLine"
The filter has a single branch: a Heartland transaction line is processed only when its line type is exactly the item type. Every other line type — including the tax and shipping lines that a Heartland invoice carries — is skipped and is not created as an iPaaS.com transaction line here. Those tax and shipping amounts are instead read into the parent invoice's header TaxAmount and ShippingAmount fields by the parent's formulas. The filter does not raise an error and throws no message; non-item lines are passed over silently.
Description: Creates an iPaaS.com Transaction Line for each item line on the Heartland invoice, carrying the product identity, quantity, and pricing values.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Static | "Product" | Type | Required. Identifies the line as a product line. iPaaS.com requires a type on every transaction line. Subscribers do not normally change this value. |
Static | "Complete" | Status | Required. Reflects that the line belongs to a completed Heartland invoice. iPaaS.com requires a status on every transaction line. Subscribers do not normally change this value. |
Field | ItemPublicId | Sku | Recommended. Stores the Heartland item's public identifier as the line SKU. The SKU should resolve to an existing iPaaS.com product or variant so the line is tied to the correct catalog item; no product prerequisite runs in this direction, so the product must already be present in iPaaS.com. |
Field | Description | Description | Recommended. Stores the Heartland invoice line's description so the line description is complete on the iPaaS.com transaction line. |
Field | Qty | Qty | Recommended. Stores the Heartland line's quantity. |
Field | FinalUnitPrice | UnitPrice | Recommended. Stores the Heartland line's final unit price, after any line discount. Used together with the original unit price to calculate the line discount amount. |
Field | CurrentUnitPrice | OriginalUnitPrice | Recommended. Captures the unit price before any line discount is applied. Used together with the final unit price to calculate the line discount amount. |
Field | Value | ExtendedPrice | Recommended. Stores the Heartland line's extended (line total) amount. |
Dynamic Formula |
| DiscountAmount | Optional. Calculates the line's discount amount as the difference between the line's original value and its final value. When an original value is present, the discount is the original value minus the final value; when no original value is present, no discount amount is set on the line. |
Field | OrderLineId | Heartland Invoice Order Line Id (custom field) | Optional. Stores the Heartland order line identifier. When an invoice is created in Heartland, the Heartland order line identifier must be included for each line item on the invoice; this mapping carries that identifier through so an integration creating invoice lines from the originating order can include it. Requires a custom field of this name on the Transaction Line collection before the value is stored. |
Field | ShipFromLocationId | Heartland Ship From Location Id (custom field) | Optional. Stores the identifier of the Heartland location the line ships from. Requires a custom field of this name on the Transaction Line collection before the value is stored. |
Static | "Heartland" | Line Created By (custom field) | Optional. Records that the line originated from Heartland. Requires a custom field of this name on the Transaction Line collection before the value is stored. |
Add Heartland Invoice Address TO iPaaS.com
This collection is a child of Add Heartland Invoice TO iPaaS.com. It does not run on its own and has no schedule, webhook, or Manual Sync entry of its own; it runs whenever the parent transfers an invoice, attaching the invoice's billing and shipping addresses to the transaction the parent created or updated. The association to that transaction is supplied automatically by the parent transfer and is not a subscriber mapping.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Attaches each address on the Heartland invoice to the iPaaS.com transaction, carrying the postal fields and the billing/shipping role indicators. iPaaS.com marks no address field as required, so every field below is optional at the platform level.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | Line1 | Address1 | Recommended. Stores the first street line of the Heartland invoice address so the iPaaS.com address is complete and usable for shipping and billing. |
Field | City | City | Recommended. Stores the city of the Heartland invoice address. |
Field | State | Region | Recommended. Stores the Heartland invoice address State in the iPaaS.com Region field. |
Field | Country | Country | Recommended. Stores the country of the Heartland invoice address. |
Field | PostalCode | PostalCode | Recommended. Stores the postal or ZIP code of the Heartland invoice address. |
Field | Line2 | Address2 | Optional. Stores the second street line of the Heartland invoice address — suite, unit, or similar. |
Field | FirstName | FirstName | Optional. Stores the first name recorded on the Heartland invoice address. This is the name on the address itself, which can differ from the customer's name. |
Field | LastName | LastName | Optional. Stores the last name recorded on the Heartland invoice address. This is the name on the address itself, which can differ from the customer's name. |
Field | IsPrimaryBilling | IsPrimaryBilling | Optional. Indicates whether this address is the invoice's billing address. Adjust this mapping if you use a field other than the Heartland IsPrimaryBilling field to indicate the billing address. |
Field | IsPrimaryShipping | IsPrimaryShipping | Optional. Indicates whether this address is the invoice's shipping address. Adjust this mapping if you use a field other than the Heartland IsPrimaryShipping field to indicate the shipping address. |
Dynamic Formula |
| ShippingMethod | Optional. Reads the shipping method name from the parent invoice and stores it on the iPaaS.com transaction address. When the parent invoice has no shipping method, no value is recorded. |
Add Heartland Invoice Payment TO iPaaS.com
This collection is a child of Add Heartland Invoice TO iPaaS.com. It does not run on its own and has no schedule, webhook, or Manual Sync entry of its own; it runs whenever the parent transfers an invoice, creating a payment record on the transaction for each Heartland payment.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Creates an iPaaS.com payment for each payment on the Heartland invoice, resolving the payment method to a configured iPaaS.com method and, for gift card payments, referencing the linked iPaaS.com gift card.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| Method | Required. Sets the payment method on the iPaaS.com payment. The formula looks up the iPaaS.com payment method linked to this Heartland payment method — matching the Heartland payment method id against an iPaaS.com payment method's external id — and uses its name. When no linked method is found, it falls back to the gift card payment method name "Gift Card_Heartland". iPaaS.com requires a payment method on every payment, and it must match the name of a payment method configured in iPaaS.com. Keep your Heartland payment methods linked, and confirm a payment method named "Gift Card_Heartland" exists so the fallback resolves to a real method. When the Heartland payment method is not yet linked, the payment method prerequisite transfers it before the invoice is transferred. |
Field | Amount | Amount | Recommended. Stores the Heartland payment amount so the payment total is complete on the iPaaS.com transaction. |
Dynamic Formula |
| Status | Optional. Translates the Heartland payment status into the iPaaS.com payment status. A Heartland "pending" payment becomes an "authorized" payment in iPaaS.com, and a Heartland "complete" payment becomes a "captured" payment; any other Heartland status leaves the iPaaS.com payment status unset. |
Field | Description | Description | Optional. Stores the Heartland payment description. For gift card payments the description is also the source the integration reads to find the gift card number, so keep it mapped if you process gift card payments. |
Dynamic Formula |
| MethodInfo | Optional in configuration, but required by iPaaS.com whenever the payment method is a gift card method. When the Heartland payment type indicates a gift card, the formula reads the gift card number from the last word of the payment description, looks up the linked iPaaS.com gift card, and — if a match is found — records its gift card id as the payment's gift card reference. For non-gift-card payments, or when no matching gift card is found, nothing is set. When the referenced gift card is not yet linked, the gift card prerequisite transfers it before the invoice is transferred. |
Field | Deposit | Heartland Payment Applied As Deposit (custom field) | Optional. Records whether the Heartland payment was applied as a deposit. Requires a custom field of this name on the Transaction Payment collection before the value is stored. |
Dynamic Formula |
| Heartland Payment Type (custom field) | Optional. Records the Heartland payment type, stripping the leading "Payments::" prefix from the raw value; when Heartland provides no payment type, nothing is stored. Requires a custom field of this name on the Transaction Payment collection before the value is stored. |
Unmapped Field Overwrite Risk
Updates in this direction are full replacements. When iPaaS.com updates a Transaction record that already exists — which happens whenever an invoice with a matching transaction number is re-transferred — the full record is replaced. Every writable iPaaS.com field that these collections do not map is overwritten with an empty value. Do not assume unmapped values are preserved.
Transaction header. The writable header fields this collection does not map are:
company_id: the alternative to a customer on the transaction. This collection supplies a customer and an email address instead, so an iPaaS.com company association set by another process is cleared on update.
transaction_created_datetime
transaction_updated_datetime
The header also carries child groups that this collection does not transfer at all: taxes, tracking, notes, and order-level discounts. Values held in those on the iPaaS.com side are not maintained here.
Transaction Line. The writable line fields the line child collection does not map are sequence_number, qty_shipped, unit, discount_percent, tax_percent, estimated_tax_amount, weight, the line-level address, options, and line_discounts.
Transaction Address. The writable address fields the address child collection does not map are shipping_method_description, shipping_amount, ship_date, type, company, phone_number, name, address_3, and the address-level customer_id.
Transaction Payment. The payment child collection maps every writable payment field that iPaaS.com exposes — method, amount, status, description, and method detail — plus its two custom fields. There is no unmapped writable payment field left that a re-transfer could clear.
The remedy. To keep a value that iPaaS.com holds but Heartland does not supply, add a mapping of type Dynamic Formula for that field whose source is DestinationValue.[FieldName] — for example DestinationValue.CompanyId to preserve the company association, or DestinationValue.Weight on the line collection to preserve a line weight. The formula reads the value currently on the iPaaS.com record and writes it back, so the update carries it forward instead of clearing it. Add one such mapping for each field you need to keep.
One field behaves differently. SystemId is flagged by iPaaS.com as not updatable and is ignored on update, so it is neither written nor cleared on an existing transaction. It takes effect only when the Transaction record is first created. The same is true of the payment method name on the Payment Method records the prerequisite creates: a rename in Heartland never propagates to an already-linked iPaaS.com payment method.
Error Handling
Customer prerequisite failed: when the invoice's Heartland customer is not yet linked and the automatic customer transfer reports errors, the invoice transfer is stopped and no iPaaS.com Transaction is created or updated. The error appears in the iPaaS.com Dashboard error logs. Resolve the customer error — most often a missing required customer value — and re-transfer the invoice.
Missing transaction number: iPaaS.com requires a transaction number on every transaction. If the mapping does not resolve, the transaction is not created. Confirm the Heartland external identifier is present on the invoice.
Duplicate transaction number: the transaction number must be unique across iPaaS.com transactions. If the plain Heartland public identifier is mapped instead of the external identifier, an order or ticket sharing the same numeric value can collide with the invoice. Map the external identifier, which carries the _INVOICE suffix.
No customer, company, or email address: iPaaS.com rejects a transaction that carries none of these. If neither the linked customer nor the customer email resolves, the transaction is not created. Confirm the invoice has a customer in Heartland and that the customer carries an email address.
Unrecognized status: a Heartland status not present in the Transaction Status lookup translation is passed through unchanged and may not be a valid iPaaS.com status, which causes the transaction to be rejected. Add a translation pair for any additional Heartland status you encounter.
SKU does not resolve: an invoice line SKU that does not match an existing iPaaS.com product or variant leaves the line unassociated with a catalog item. No product prerequisite runs in this direction, so transfer your Heartland products to iPaaS.com before transferring invoices.
Payment method not configured: the payment method name must match a payment method configured in iPaaS.com. When no linked method resolves, the mapping falls back to "Gift Card_Heartland"; if no method of that name exists in iPaaS.com, the payment is rejected. Create it, or keep the Heartland payment methods linked.
Gift card reference missing: iPaaS.com requires a gift card id on any payment whose method is a gift card method. If the gift card number cannot be read from the last word of the payment description, or the gift card is not linked in iPaaS.com, the payment is rejected. Confirm the Heartland payment description ends with the gift card number.
Custom value not stored: when a custom field mapped by these collections does not exist on the corresponding iPaaS.com collection, the invoice still transfers and its other fields are written; only that custom value is not retained. Create the custom field and re-transfer to populate it.
Invoice not found: when a Manual Sync is run for a Heartland transaction ID that does not exist, or the record cannot be retrieved, the transfer fails and no iPaaS.com record is created or updated. Confirm the ID is correct and that the invoice is still present in Heartland.
Heartland API unavailable: if the Heartland API is temporarily unavailable when a transfer is triggered, the transfer fails, including its lines, addresses, and payments. The error appears in the iPaaS.com Dashboard error logs, and the record can be retried through a new polling cycle or Manual Sync.
Invoice silently skipped: an invoice that does not satisfy the parent filter produces no error at all. If an expected invoice never arrives, confirm it is complete in Heartland, that its external identifier contains _INVOICE and does not end with -D, and that its Transaction Source custom field is not "iPaaS.com".
Testing & Validation
Test Scenarios
New invoice created — complete an invoice in Heartland, transfer it, and confirm an iPaaS.com Transaction of type Invoice is created with the transaction number in the {invoice_number}_INVOICE format.
Existing invoice updated — change a value on a linked Heartland invoice, transfer it again, and confirm the same iPaaS.com Transaction is updated with no duplicate created.
System id ignored on update — re-transfer a linked invoice and confirm the iPaaS.com transaction remains on the same subscription. The system id is applied on create only and is ignored on update.
Payment method rename does not propagate — rename a linked Heartland payment method, transfer an invoice that uses it, and confirm the iPaaS.com Payment Method name is unchanged. The name is applied on create only.
Incomplete invoice skipped — transfer an invoice that is not yet complete in Heartland and confirm no iPaaS.com Transaction is created and no error is logged.
Deposit skipped — transfer a Heartland transaction whose external identifier ends with -D and confirm it is passed over by this collection.
Feedback loop prevented — take an invoice whose Transaction Source custom field is "iPaaS.com" and confirm it is not transferred back into iPaaS.com.
Order and ticket skipped — transfer a Heartland sales order and a ticket and confirm neither is picked up by this collection.
Customer auto-transferred — transfer an invoice for a Heartland customer not yet linked to iPaaS.com and confirm the customer is created in iPaaS.com automatically, before the invoice, without any manual pre-sync.
Customer prerequisite failure blocks the invoice — force the customer transfer to fail and confirm the invoice is not created in iPaaS.com and the error is logged.
Payment method auto-transferred — transfer an invoice paid with a Heartland payment method not yet linked to iPaaS.com and confirm the payment method is created in iPaaS.com and the payment references it.
Gift card payment — transfer an invoice with a gift card payment and confirm the gift card is linked, the payment references its gift card id, and the payment method resolves.
Gift card fallback — transfer a gift card payment whose method does not resolve and confirm it is recorded under the "Gift Card_Heartland" payment method.
Item lines only — transfer an invoice carrying tax and shipping lines and confirm only the item lines become iPaaS.com transaction lines, while the tax and shipping amounts appear in the header TaxAmount and ShippingAmount.
Line discount calculated — transfer an invoice line with an original value greater than its final value and confirm the line discount amount equals the difference.
Addresses attached — transfer an invoice with distinct billing and shipping addresses and confirm both are attached to the iPaaS.com transaction with the correct role indicators.
Order-to-invoice link — transfer an invoice whose originating Heartland order is already linked, and confirm the iPaaS.com invoice is created as a child of that order's transaction.
Cascade deletion — with the ParentId mapping in place, delete the parent order in iPaaS.com and confirm the linked invoice is deleted with it. Run this in staging only.
Unmapped field cleared — set a value on an unmapped writable field in iPaaS.com (for example a line weight), re-transfer the invoice, and confirm the value is cleared. Then add the DestinationValue preservation mapping and confirm it survives the next re-transfer.
Custom fields populated — with all custom fields created on the Transaction, Transaction Line, and Transaction Payment collections, transfer an invoice and confirm each Heartland value is stored.
Custom field absent — remove one custom field, transfer an invoice, and confirm the record still transfers with the remaining fields written and no error raised for the missing custom value.
SKU not in iPaaS.com — transfer an invoice whose line SKU has no matching iPaaS.com product and confirm the behavior, then transfer the product and re-transfer the invoice.
Manual Sync by ID — enter a known Heartland transaction ID for an invoice on the Manual Sync page and confirm that invoice and its children transfer.
Polling — with the subscription enabled, complete an invoice in Heartland and confirm it arrives in iPaaS.com on the next polling cycle without manual intervention.
Validation Checklist
Every transferred invoice carries a transaction number in the {invoice_number}_INVOICE format, and re-transfers update rather than duplicate.
Only invoices that are complete in Heartland appear in iPaaS.com; deposits, orders, and tickets do not.
Each transaction has a resolved customer or an email address, and a status that is valid in iPaaS.com.
Header TaxAmount and ShippingAmount match the invoice's tax and shipping lines in Heartland.
Only item lines appear as iPaaS.com transaction lines, and each line SKU resolves to an existing product or variant.
Billing and shipping addresses are attached with the correct role indicators.
Every payment carries a method that matches a configured iPaaS.com payment method, and gift card payments carry a gift card reference.
Customers, payment methods, and gift cards that were not previously linked were created automatically, without manual pre-sync.
Every writable field you rely on is either mapped or has a DestinationValue preservation mapping, verified by re-transferring an existing invoice and confirming nothing you need was cleared.
Polling and Manual Sync produce the same resulting record for the same invoice.
Additional Notes
Heartland is the source of truth for the fields listed under Mappings. Editing those values directly in iPaaS.com will be overwritten on the next transfer of that invoice.
The three child collections are transferred as part of the parent invoice transfer. They cannot be run, scheduled, or manually synced on their own.
Because invoices arrive by polling rather than instant webhooks, allow for the polling interval when validating a change made in Heartland.
The Transaction Created By custom field is not decorative. It is the marker the outbound direction reads to avoid sending iPaaS.com-created transactions back into iPaaS.com; leave it mapped whenever both directions are active.
The C5_Custom_Transaction mapping ships with a placeholder Heartland custom field name. Replace it with a real Heartland custom field name, or remove the mapping, before going live.
Related Documents
Setup & Reference
Mapping Documentation