Summary
Heartland payment methods are transferred into iPaaS.com as Payment Method records. A single Add/Update collection handles both creating new iPaaS.com payment methods and updating those already linked to Heartland, so the same flow covers a payment method's whole life cycle.
For each payment method the integration maps the Heartland payment method name to the iPaaS.com Name, derives a Description from the Heartland payment method kind, and determines the iPaaS.com PaymentType from the payment method name. Payment methods are reference data used elsewhere in the integration to classify how a transaction was paid, so keeping them current in iPaaS.com supports accurate downstream reporting.
This is an inbound-only area (Heartland to iPaaS.com). There is no opposite-direction collection that writes payment methods back to Heartland.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the Heartland payment method ID — for example, 100014.
External ID Format
After a successful transfer, the Heartland payment method ID is saved as the external-id link between the two systems (for example, 100014). Subsequent transfers update the same iPaaS.com Payment Method record rather than creating a duplicate. Whether an incoming payment method is created or updated in iPaaS.com is determined by whether it is already linked by an external id, not by which event triggered the transfer.
Deleted Record Support
Deleting a payment method is not supported in this direction. The integration creates and updates iPaaS.com Payment Method records only — removing a payment method in Heartland does not delete or deactivate the linked iPaaS.com Payment Method record. Payment methods that are no longer in use should be managed directly in iPaaS.com.
Mapping Collection Status
Status: Enabled.
Trigger Events: Automatic transfers run on a schedule through polling. Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so payment methods arrive through polling rather than instant push notifications. Polling does not run until the subscription is configured and enabled. All eligible payment methods can also be transferred immediately from the Initialize Data section of the Heartland subscription in iPaaS.com, and individual payment methods can be transferred at any time from the Manual Sync page. Payment method creation, update, and polling events are all available for this area.
Duplicate or Conflicting Mappings
No other mapping collection in this integration operates on Payment Method reference records, and there is no opposing iPaaS.com to Heartland Payment Method collection, so there is no two-direction overwrite concern.
The other Heartland collections whose names include "Payment" — for example the Sales Order, Ticket, and Invoice payment collections — transfer payment transactions recorded against orders, tickets, and invoices. Those are a different data type and do not compete with this collection for the same records.
Because a single Add/Update collection serves both new and existing records, there is no separate Add collection that could compete with an Update collection for the same payment method.
Collision Handling
This integration does not use iPaaS.com collision handling for payment methods. Whether an incoming payment method is created or updated is determined solely by whether it is already linked by an external id; there is no collision recovery step to configure.
Supported Child Collections
None. This is a standalone collection with no dependent child collections.
System Caveats
Heartland Caveats
Heartland requires a name on a payment method. Supply it so the payment method can be created and so its iPaaS.com payment type can be determined from it.
Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so payment methods are picked up by polling rather than pushed instantly. Expect a delay between a change in Heartland and its arrival in iPaaS.com, bounded by the polling schedule.
iPaaS.com Caveats
The Name field is required on every iPaaS.com Payment Method record. Without it the payment method is not created.
The PaymentType field is required, and its value must be one of the accepted iPaaS.com payment types: A R, Cash, Check, Credit Card, Debit Card, Gift Card, Loyalty, Store Credit, Ebt, or Online. A value outside this set is not accepted.
The Description field is optional in iPaaS.com.
Integration-Specific Caveats
The payment type determination recognizes only the standard Heartland starter payment method names. A payment method whose name is not one of those recognized names transfers to iPaaS.com as Cash unless the PaymentType mapping is extended to cover it.
Transfers are additive and update-in-place: an incoming payment method never removes an existing iPaaS.com Payment Method record.
Only the fields listed under Mappings are written. Any other field on the iPaaS.com Payment Method record is left untouched by this collection.
Payment Method is one of only three areas in this integration that support Initialize Data. The others are Location and Shipping Method. All other Heartland areas are transferred by polling or Manual Sync only.
Setup Requirements
Heartland Configuration
Ensure each payment method has a Name, which Heartland requires and which the integration also uses to determine the iPaaS.com payment type.
Review your Heartland payment method names before the first transfer. Names beyond the standard starter set resolve to Cash unless the PaymentType mapping is adjusted.
iPaaS.com Configuration
Ensure the Name mapping resolves — it is required for the record to be created.
Ensure the PaymentType mapping resolves to one of the accepted iPaaS.com payment types. Extend it to cover any additional or renamed Heartland payment methods so they do not all transfer as Cash.
Enable the subscription so polling can run, or use Initialize Data to transfer all existing payment methods on demand.
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 payment methods changed in Heartland since the previous poll.
For each payment method returned, it retrieves the full Heartland payment method record.
Each record is dispatched to iPaaS.com through the Payment Method collection, where it is created if not yet linked, or updated if the Heartland payment method ID is already saved as the external id.
Initialize Data:
From the Initialize Data section of the Heartland subscription, the integration requests all payment methods from Heartland in one pass.
Each payment method is retrieved individually and dispatched exactly as in the polling flow, so a subscription can be brought fully up to date without waiting for the next poll.
Manual Sync:
A Heartland payment method ID is entered on the iPaaS.com Manual Sync page.
The integration retrieves that single payment method from Heartland and dispatches it through the same create-or-update path.
All three paths converge on the same mapping logic, so a payment method's resulting iPaaS.com record is identical regardless of how the transfer was triggered. This collection has no auto-transferred prerequisites: the payment method record is dispatched on its own, with no other record transferred ahead of it.
Mappings
Add/Update Heartland Payment Method TO iPaaS.com
Mapping Filter
This mapping collection does not have a mapping filter applied. All Heartland payment method records received through polling, Initialize Data, or Manual Sync are processed without additional filtering conditions.
Description: Creates or updates the iPaaS.com Payment Method record from the Heartland payment method, matched durably by the Heartland payment method ID. That ID is saved as the record's external id and is the durable match key; it is not a configurable mapping row.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| Name | Required. Stores the Heartland payment method's name in the iPaaS.com Name field. iPaaS.com will not create a payment method without a name, and the name is also the value the PaymentType mapping uses to determine the payment type. |
Dynamic Formula |
| Description | Optional. Derives the iPaaS.com Description from the Heartland payment method kind. A kind identifying a standard payment type produces "CustomPayment"; a kind identifying a gift-card payment type produces "GiftCardPayment". Any other kind, or a payment method with no kind, produces no description, and the payment method still transfers. |
Dynamic Formula |
| PaymentType | Required. Translates the Heartland payment method name into the corresponding iPaaS.com payment type. The standard Heartland starter payment method names are recognized and resolve to Cash, Check, Gift Card, Credit Card, and Debit Card respectively. When the name is not one of those recognized names, the payment type defaults to Cash so the record still transfers. The stored value must be one of the accepted iPaaS.com payment types listed under iPaaS.com Caveats. |
Unmapped Field Overwrite Risk
The iPaaS.com Payment Method record exposes five writable values: Name, Description, Payment Type, custom fields, and external ids. This collection maps Name, Description, and Payment Type; it does not map custom fields. If your integration stores values in iPaaS.com Payment Method custom fields from another source, confirm they are preserved before running updates — to keep one, add a Dynamic Formula mapping whose source is DestinationValue.[FieldName], which reads the current iPaaS.com value and writes it back.
Note that Name is set only when the record is created. On an update it is ignored, so renaming a payment method in Heartland does not rename the linked iPaaS.com Payment Method record. To change the name in iPaaS.com, edit it there directly.
Error Handling
Missing payment method name: the Name is required in iPaaS.com. When Heartland does not supply a name, or the Name mapping does not resolve, the iPaaS.com Payment Method record is not created. Populate the Name in Heartland and confirm the mapping resolves before retrying.
Payment type not recognized: when the Heartland payment method name is not one of the recognized starter names, the transfer still succeeds but the payment type is stored as Cash. This is not reported as an error, so review the payment types on transferred records if your Heartland account uses custom payment method names, and extend the PaymentType mapping to cover them.
Payment type outside the accepted set: iPaaS.com accepts only its defined payment types. If the PaymentType mapping is edited to return a value outside that set, the payment method is rejected. Restore the mapping so it returns one of the accepted values.
Payment method not found: when a Manual Sync is run for a payment method ID that does not exist in Heartland, 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 payment method is still present in Heartland.
Heartland temporarily unavailable: if the Heartland API cannot be reached when a transfer is triggered, the transfer fails. The error appears in the iPaaS.com Dashboard error logs, and the record is picked up again on a later polling cycle or can be retried through Manual Sync.
Testing & Validation
Test Scenarios
New payment method created — create a payment method in Heartland with a name, transfer it, and confirm an iPaaS.com Payment Method record is created with the matching name and linked by the Heartland payment method ID.
Existing payment method updated — rename a linked Heartland payment method, transfer it again, and confirm the same iPaaS.com record is updated with no duplicate created.
No duplicate on re-transfer — transfer the same payment method twice and confirm only one iPaaS.com Payment Method record exists.
Recognized payment type — transfer each of the standard Heartland starter payment methods and confirm each resolves to the expected iPaaS.com payment type rather than defaulting.
Unrecognized name defaults to Cash — transfer a payment method with a custom name and confirm the iPaaS.com payment type is stored as Cash.
Description derived from kind — transfer a standard payment method and a gift-card payment method and confirm the expected description value is stored for each.
Description absent — transfer a payment method whose kind produces no description and confirm the record is still created with the Description left empty.
Manual Sync by ID — enter a known Heartland payment method ID on the Manual Sync page and confirm that specific payment method transfers.
Initialize Data — run Initialize Data and confirm all eligible Heartland payment methods are transferred in one pass.
Polling — with the subscription enabled, create a payment method in Heartland and confirm it arrives in iPaaS.com on the next polling cycle without manual intervention.
Validation Checklist
The Name is populated in Heartland and resolves through the mapping on every transferred record.
The PaymentType on every transferred record is one of the accepted iPaaS.com payment types.
Payment methods with custom names have been reviewed, and any that should not be Cash have had the PaymentType mapping extended.
Each transferred payment method is linked by the Heartland payment method ID, and re-transfers update rather than duplicate.
Fields not listed under Mappings are unchanged after a transfer.
Polling, Initialize Data, and Manual Sync all produce the same resulting record for the same payment method.
Additional Notes
A single Add/Update collection covers both creation and updates. There is no separate Add or Update collection for payment methods, so no configuration choice is needed between them.
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 payment method.
Because payment methods arrive by polling rather than instant webhooks, allow for the polling interval when validating a change made in Heartland.
Payment methods are reference data. Transferring them before transactional data helps ensure downstream records can be classified by how they were paid.
Related Documents
Setup & Reference